sentry/docs-ui/stories/gettingStarted/gettingStarted.stories.mdx

import StylesVariantsComponents from './styles-variants-components.svg';

<Meta title="Getting Started" />

# Getting Started

👋 Hello there! You've arrived at Sentry's Design System guidebook. Here, you will find a detailed account of our UI system, including interactive examples and recommended use cases. We want to have appropriate and consistent use of our components, so that's why this guidebook exists!

---

## Structure

- **`CORE`**: foundational styles that are used throughout the entire UI system, like color, typography,…
- **`ASSETS`**: logos, images, icons,…
- **`COMPONENTS`**: reusable components, with detailed descriptions and recommended use cases
- **`VIEWS`**: layouts and other UI groups that are composed of multiple components
- **`UTILITIES`**: UI-related functions, like text formatters, truncators,…
- **`DEPRECATED`**: legacy components that should no longer be used; they are here for documentation purposes only

---

## Usage

Here's how to make the best use of this guide:

- Press `/` to perform a quick search, you can search by category or component name
- When viewing components, check out the `Control`, `Accessibility`, and other useful tabs in the bottom panel
- Play around with features in the top bar, you can:
  - Zoom in/out
  - Simulate screen sizes
  - See what the component looks like for color-blind users
- Ping Vu Luong or someone in the Product Design team if you're not sure about anything related to UI systems

---

## Styles, variants, and components

Sentry's UI system has three fundamental building blocks: styles, variants, and components. You will see these concepts mentioned throughout this guide, so it's good to understand what each of them means and how they are different from one another.

**Styles** are specific definitions/assignments for UI attributes, like background color, font size, and border. For example, `background-color: #FFFFFF` is a style.

**Variants** are predefined style combinations. For example, we can define a `primary` variant for buttons that consists of the following styles: `background color: #6C5FC7`, `text color: #FFFFFF`, and `border: 1px #3E2C73`. (Note: we use hard-coded values, like `#6C5FC7`, for demonstration purposes only. We strongly discourage using them in the code. Instead, use predefined variables like `theme.backgroundColor`.)

**Components** are flexible, reusable UI elements such as buttons, dialogs, and badges. A component can adopt one of many variants, and one or more styles. For example, a button can adopt a `primary` or `secondary` variant. It can also use one or more additional styles if the variant definitions are not enough.

<img
  src={StylesVariantsComponents}
  alt="Diagram with three columns: Styles, Variants, and Components"
/>

---

## Updates

Check out the Changelog page for the latest updates.

<DocsLinks
  links={[
    {
      img: {
        src: require('docs-ui/images/changelog-link-preview.svg'),
        alt: 'Outline of list with bullet points',
      },
      title: 'Changelog',
      desc: 'Latest updates to the design and component system',
      kind: 'Changelog',
      story: 'Page',
    },
  ]}
/>

---

<h2 className="hide-from-toc">Read on</h2>

Start reading now with these foundational topics.

<DocsLinks
  links={[
    {
      img: {
        src: require('docs-ui/images/colors-link-preview.svg'),
        alt: 'Various shapes in Sentry colors',
      },
      title: 'Colors',
      kind: 'Core/Colors',
      desc: 'Colors and how to apply them in a usable, accessible manner',
      story: 'Page',
    },
    {
      img: {
        src: require('docs-ui/images/typography-link-preview.svg'),
        alt: 'Text sample of characters "A", "z", "0", and "9" with grid lines in the background',
      },
      title: 'Typography',
      desc: 'The type system and text styling rules',
      kind: 'Core/Typography',
      story: 'Page',
    },
    {
      img: {
        src: require('docs-ui/images/icons-link-preview.svg'),
        alt: 'Large colorful icons',
      },
      title: 'Icons',
      desc: 'Search for icons and get copiable code snippets',
      kind: 'Assets/Icons',
      story: 'Page',
    },
  ]}
/>