sentry/docs-ui/stories/core/overview.stories.mdx

import { Meta } from '@storybook/addon-docs';
import StylesVariantsComponets from '../../images/core-overview-styles-variants-components.png';

<Meta title="Core/Overview" />

# Overview 

👋 Hello there! You've arrived at Sentry's UI 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={StylesVariantsComponets} alt="Diagram with three columns: Styles, Variants, and Components" />