@beam-ui/design-tokens 1.0.0 → 2.0.0

package/USAGE.md

@@ -1,286 +0,0 @@
-# Beam UI Design Tokens - Usage Guide
-
-A centralized collection of design decisions and other artifacts for the Beam UI Design System.
-
-## Overview
-
-Design tokens are the visual design atoms — specifically, they are named entities that store various design decisions. This package provides these tokens in multiple formats for consistent use across applications.
-
-## Installation
-
-```bash
-npm install @beam-ui/design-tokens
-# or
-yarn add @beam-ui/design-tokens
-```
-
-## Available Output Formats
-
-All tokens are available in three formats:
-- **CSS Variables** (`variables.css`) - CSS custom properties
-- **JavaScript ES6** (`tokens.es6.js`) - ES6 module exports
-- **JSON** (`tokens.json`) - Nested JSON structure
-
-## Token Layers
-
-Tokens are organized in three layers:
-
-- **`build/globals/`** - Global tokens (breakpoints, accessibility, etc.)
-- **`build/base/`** - Default base tokens (colors, fonts, spacing, etc.)
-- **`build/semantic/`** - Default semantic tokens (buttons, typography, etc.)
-
-Brand-specific tokens can be found at `build/{brand}/base/` and `build/{brand}/semantic/` if custom brands exist.
-
-## Usage
-
-### Using CSS Variables
-
-#### Important: Semantic Tokens Require Base and Global Tokens
-
-**Semantic CSS tokens reference base and global tokens using CSS custom properties (`var()`)**, which means you must import all token files in the correct order for semantic tokens to work correctly.
-
-#### Recommended Import Order
-
-```css
-/* Import in this order: */
-@import '@beam-ui/design-tokens/build/globals/variables.css';
-@import '@beam-ui/design-tokens/build/base/variables.css';
-@import '@beam-ui/design-tokens/build/semantic/variables.css';
-```
-
-Or in your HTML:
-```html
-<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/globals/variables.css">
-<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/base/variables.css">
-<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/semantic/variables.css">
-```
-
-#### Why All Three Files Are Required
-
-Tokens use `var()` references to maintain relationships across all layers:
-
-```css
-/* 1. Global tokens define shared values */
-:root {
-  --breakpoint-medium: 768px;
-  --a11y-min-touch-target: 40px;
-}
-
-/* 2. Base tokens define the actual brand values */
-:root {
-  --color-gray-black: hsl(0, 0%, 0%);
-  --color-gray-white: hsl(0, 0%, 100%);
-  --color-transparent: hsla(0, 0%, 0%, 0);
-  --font-size-medium: 1.6rem;
-}
-
-/* 3. Semantic tokens reference base and global tokens */
-:root {
-  --button-primary-background: var(--color-gray-black);
-  --button-primary-text: var(--color-gray-white);
-  --button-tertiary-border: var(--color-transparent);
-  --button-primary-font-size: var(--font-size-medium);
-  --button-size-sm-min-width: var(--a11y-min-touch-target);
-}
-```
-
-#### Benefits of This Approach
-
-- **Single source of truth** - Update base token values and all semantic tokens automatically reflect the change
-- **Smaller file sizes** - References are more efficient than duplicated values
-- **Runtime flexibility** - Override base tokens to theme entire components
-- **Maintainability** - Clear relationships between foundation and application layers
-
-#### Using Only Base Tokens
-
-If you only need base tokens (colors, spacing, fonts) without semantic tokens, you can import just the base and global files:
-
-```css
-@import '@beam-ui/design-tokens/build/globals/variables.css';
-@import '@beam-ui/design-tokens/build/base/variables.css';
-
-.custom-button {
-  background-color: var(--color-gray-black);
-  padding: var(--spacing-medium);
-  font-size: var(--font-size-medium);
-  min-height: var(--a11y-min-touch-target);
-}
-```
-
-**Note:** Base tokens may reference global tokens (like accessibility values), so it's recommended to include globals even when not using semantic tokens.
-
-### Using JavaScript/TypeScript Tokens
-
-JavaScript and JSON formats output resolved values, so semantic tokens can be used independently:
-
-```javascript
-// Semantic tokens contain resolved values
-import { buttonPrimaryBackground, buttonPrimaryText } from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';
-
-const button = {
-  backgroundColor: buttonPrimaryBackground, // "hsl(0, 0%, 0%)"
-  color: buttonPrimaryText // "hsl(0, 0%, 100%)"
-};
-```
-
-#### Importing Base Tokens
-
-```javascript
-import { colorGrayBlack, fontSizeMedium, spacingLarge } from '@beam-ui/design-tokens/build/base/tokens.es6.js';
-
-const styles = {
-  color: colorGrayBlack, // "hsl(0, 0%, 0%)"
-  fontSize: fontSizeMedium, // "1.6rem"
-  padding: spacingLarge // "2.4rem"
-};
-```
-
-#### Importing Global Tokens
-
-```javascript
-import { breakpointMedium, a11yMinTouchTarget } from '@beam-ui/design-tokens/build/globals/tokens.es6.js';
-
-const config = {
-  breakpoint: breakpointMedium, // "768px"
-  minTouchSize: a11yMinTouchTarget // "40px"
-};
-```
-
-### Using JSON Tokens
-
-JSON format provides a nested structure:
-
-```javascript
-import tokens from '@beam-ui/design-tokens/build/semantic/tokens.json';
-
-console.log(tokens.button.primary.background); // "hsl(0, 0%, 0%)"
-console.log(tokens.color.background.primary); // "hsl(0, 0%, 100%)"
-```
-
-## Token Reference
-
-### Global Tokens
-
-**Breakpoints**
-- `breakpoint-small`, `breakpoint-medium`, `breakpoint-large`, `breakpoint-x-large`
-
-**Accessibility**
-- `a11y-min-touch-target` - Minimum touch target size for interactive elements
-
-### Base Tokens
-
-**Colors**
-- Brand colors: `color-tatari-red`, `color-tatari-blue`, etc.
-- Gray scale: `color-gray-black`, `color-gray-800` through `color-gray-50`, `color-gray-white`
-- Color palettes: `color-red-*`, `color-blue-*`, `color-green-*`, etc. (100-700 scales)
-- Special: `color-transparent`, `color-overlay-dark`, `color-overlay-light`
-
-**Typography**
-- Font sizes: `font-size-xx-small` through `font-size-xxx-large`
-- Line heights: `line-height-xx-small` through `line-height-xxx-large`
-- Letter spacing: `letter-spacing-xx-small` through `letter-spacing-xxx-large`
-
-**Spacing**
-- `spacing-xx-small` through `spacing-xxx-large`
-
-**Borders**
-- Border radius: `border-radius-xx-small` through `border-radius-xxx-large`, `border-radius-circle`
-- Border width: `border-width-thin`, `border-width-regular`, `border-width-thick`
-
-### Semantic Tokens
-
-**Button Tokens**
-- Variants: `button-primary-*`, `button-secondary-*`, `button-tertiary-*`
-- Danger states: `button-danger-primary-*`, `button-danger-secondary-*`
-- States: `-background`, `-background-hover`, `-background-active`, `-background-disabled`
-- Text: `-text`, `-text-hover`, `-text-active`, `-text-disabled`
-- Border: `-border`, `-border-hover`, `-border-active`, `-border-disabled`
-- Sizes: `button-size-sm-*`, `button-size-md-*`, `button-size-lg-*`
-
-**Color Tokens**
-- Background: `color-background-primary`, `color-background-secondary`, etc.
-- Surface: `color-surface-primary`, `color-surface-hover`, etc.
-- Border: `color-border-primary`, `color-border-focus`, etc.
-- Text: `color-text-primary`, `color-text-link`, etc.
-- Icon: `color-icon-primary`, `color-icon-interactive`, etc.
-- Interactive states: `color-interactive-primary-default`, etc.
-- Status colors: `color-status-success-base`, `color-status-error-base`, etc.
-- Brand colors: `color-brand-primary-base`, `color-brand-secondary-base`, etc.
-
-**Typography Tokens**
-- Headings: `typography-heading-100-*` through `typography-heading-600-*`
-- Body text: `typography-body-100-*`, `typography-body-200-*`
-- Captions: `typography-caption-100-*`, `typography-caption-200-*`
-- Properties: `-font-size`, `-line-height`, `-letter-spacing`
-
-## Examples
-
-### Complete Button Component (CSS)
-
-```css
-/* Import all required token files */
-@import '@beam-ui/design-tokens/build/globals/variables.css';
-@import '@beam-ui/design-tokens/build/base/variables.css';
-@import '@beam-ui/design-tokens/build/semantic/variables.css';
-
-.button-primary {
-  background-color: var(--button-primary-background);
-  color: var(--button-primary-text);
-  border: var(--button-primary-border-width) solid var(--button-primary-border);
-  border-radius: var(--button-primary-border-radius);
-  font-size: var(--button-primary-font-size);
-  line-height: var(--button-primary-line-height);
-  padding-inline: var(--button-size-md-padding-inline);
-  padding-block: var(--button-size-md-padding-block);
-  min-width: var(--button-size-md-min-width);
-}
-
-.button-primary:hover {
-  background-color: var(--button-primary-background-hover);
-  color: var(--button-primary-text-hover);
-  border-color: var(--button-primary-border-hover);
-}
-```
-
-### React Component with TypeScript
-
-```typescript
-import {
-  buttonPrimaryBackground,
-  buttonPrimaryText,
-  buttonPrimaryBorderRadius,
-  buttonSizeMdPaddingInline,
-  buttonSizeMdPaddingBlock
-} from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';
-
-interface ButtonProps {
-  children: React.ReactNode;
-}
-
-export const Button: React.FC<ButtonProps> = ({ children }) => {
-  return (
-    <button
-      style={{
-        backgroundColor: buttonPrimaryBackground,
-        color: buttonPrimaryText,
-        borderRadius: buttonPrimaryBorderRadius,
-        paddingInline: buttonSizeMdPaddingInline,
-        paddingBlock: buttonSizeMdPaddingBlock
-      }}
-    >
-      {children}
-    </button>
-  );
-};
-```
-
-## Support
-
-For issues, questions, or contributions, please visit:
-- [GitHub Repository](https://github.com/tatari-tv/beam-ui)
-- [Issue Tracker](https://github.com/tatari-tv/beam-ui/issues)
-
-## License
-
-MIT
-