import { Canvas, Meta, Title, Subtitle } from '@storybook/addon-docs/blocks'
import * as SemanticStories from './Semantic.stories'
import { LifecycleTag } from '../../docs/components'
import { tokens } from '../../theme/tokens/tokens'

<Meta title="Theme/Tokens/Docs" />

<Title>Semantic Tokens</Title>
<Subtitle>
  The foundation of our theming system - semantic design tokens that
  automatically adapt to light and dark modes.
</Subtitle>
<LifecycleTag variant="Stable" />

## Overview

Semantic tokens are the **foundation** of the Blocks design system. They provide meaningful, context-aware color values that automatically switch between light and dark modes when the `.dark` class is applied to your HTML element.

**Always use semantic tokens** instead of raw color values to ensure your UI adapts correctly to theme changes.

These tokens reference the underlying [Color Palette](?path=/docs/theme-colorpalette--docs), abstracting raw colors like `--blue-700` into semantic meanings like `--primary`.

## How to Use

Reference tokens as CSS custom properties:

```css
.my-element {
  background-color: var(--background);
  color: var(--foreground);
  border-color: var(--border);
}
```

Or use the corresponding Tailwind classes:

```tsx
<div className="border-border bg-background text-foreground">Content</div>
```

## Quick Reference

<div className="rounded-md bg-gray-900 p-4 font-mono text-sm text-gray-100">
  {Object.entries(tokens).map(([categoryName, categoryTokens]) => (
    <div key={categoryName} className="mb-4">
      <div className="mb-1 text-gray-400">/* {categoryName} */</div>
      {Object.entries(categoryTokens).map(([tokenName]) => (
        <div key={tokenName} className="text-green-400">
          --{tokenName}
        </div>
      ))}
    </div>
  ))}
</div>

## All Tokens

Below is the complete list of semantic tokens with their light and dark mode values:

<Canvas of={SemanticStories.SemanticTokens} />