@beam-ui/design-tokens 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @beam-ui/design-tokens
 
+## 1.0.1
+
+### Patch Changes
+
+- The README was renamed to CONTRIBUTING and the USAGE to README in order to improve the documentation on the npm side
+
 ## 1.0.0
 
 ### Major Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tatari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,394 +1,280 @@
 # Beam UI Design Tokens
 
-A centralized collection of design decisions and other artifacts for the Beam UI Design System. This package uses [Style Dictionary](https://styledictionary.com/) to transform design tokens into multiple formats.
-
-> **For usage and consumption documentation**, see [USAGE.md](./USAGE.md) (included in the npm package).
+A centralized collection of design decisions and other artifacts for the Beam UI Design System.
 
 ## Overview
 
-This repository manages design tokens that define the visual design language for Beam UI. Tokens are authored in JavaScript and transformed into CSS Variables, JavaScript ES6 modules, and JSON formats using Style Dictionary.
+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
-# Install dependencies
-yarn install
-```
-
-## Building Tokens
-
-To build the design tokens into all output formats:
-
-```bash
-yarn build
+npm install @beam-ui/design-tokens
+# or
+yarn add @beam-ui/design-tokens
 ```
 
-This will generate tokens in the following formats:
-- **CSS Variables** (`variables.css`)
-- **JavaScript ES6** (`tokens.es6.js`)
-- **JSON** (`tokens.json`)
-
-All generated files are located in the `build/` directory, organized by layer:
-- `build/globals/` - Global tokens (breakpoints, accessibility, etc.)
-- `build/base/` - Default base tokens (colors, fonts, spacing, etc.)
-- `build/semantic/` - Default semantic tokens (buttons, typography, etc.)
-- `build/{brand}/base/` - Brand-specific base tokens (if custom brands exist)
-- `build/{brand}/semantic/` - Brand-specific semantic tokens (if custom brands exist)
+## Available Output Formats
 
-## Token Structure
+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
 
-### Source Organization
+## Token Layers
 
 Tokens are organized in three layers:
 
-#### Global Tokens (`src/tokens/globals/`)
-Global tokens shared across all themes:
-- `breakpoints.js` - Responsive breakpoints
-- `a11y.js` - Accessibility-related tokens (touch target sizes, etc.)
+- **`build/globals/`** - Global tokens (breakpoints, accessibility, etc.)
+- **`build/base/`** - Default base tokens (colors, fonts, spacing, etc.)
+- **`build/semantic/`** - Default semantic tokens (buttons, typography, etc.)
 
-#### Base Tokens (`src/tokens/base/`)
-Default foundation design values:
-- `color.js` - Color palette including brand colors, color scales, and utility colors
-- `font.js` - Font families, sizes, line heights, letter spacing
-- `spacing.js` - Spacing scale
-- `border.js` - Border radius and width values
+Brand-specific tokens can be found at `build/{brand}/base/` and `build/{brand}/semantic/` if custom brands exist.
 
-#### Semantic Tokens (`src/tokens/semantic/`)
-Default component-specific tokens that reference base tokens:
-- `color.js` - Semantic color assignments (text, background, border, icon, status, etc.)
-- `typography.js` - Typography styles (headings, body text, captions, etc.)
-- `button.js` - Button component tokens (variants, states, sizes, etc.)
+## Usage
 
-#### Brand-Specific Tokens (`src/tokens/brands/{brand}/`)
-Optional brand overrides following the same base/semantic structure
+### Using CSS Variables
 
-### Token Format
+#### Important: Semantic Tokens Require Base and Global Tokens
 
-All tokens follow the W3C Design Token format and must include:
-- `value` - The token value (can be a literal value or reference to another token)
-- `type` - The token type (color, dimension, fontSize, fontFamily, etc.)
+**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.
 
-**Example - Base Token:**
-```javascript
-export default {
-  color: {
-    'tatari-red': {
-      value: 'hsl(2, 72%, 46%)',
-      type: 'color'
-    },
-    gray: {
-      black: {
-        value: 'hsl(0, 0%, 0%)',
-        type: 'color'
-      }
-    }
-  }
-};
-```
+#### Recommended Import Order
 
-**Example - Semantic Token (with references):**
-```javascript
-export default {
-  button: {
-    primary: {
-      background: {
-        value: '{color.gray.black}', // References base token
-        type: 'color'
-      }
-    }
-  }
-};
+```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';
 ```
 
-**Important:** For colors with alpha channels, use comma-based syntax:
-```javascript
-// ✅ Correct
-value: 'hsla(0, 0%, 0%, 0.3)'
-
-// ❌ Incorrect (CSS Color Level 4 slash syntax not supported)
-value: 'hsl(0 0% 0% / 0.3)'
+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">
 ```
 
-## Adding New Tokens
+#### Why All Three Files Are Required
 
-### 1. Create or edit token files
-
-Add tokens to the appropriate file in `src/tokens/base/`, `src/tokens/semantic/`, or `src/tokens/globals/`:
-
-```javascript
-// Example: Adding a new spacing value to src/tokens/base/spacing.js
-export default {
-  spacing: {
-    'xxxx-large': {
-      value: '6.4rem',
-      type: 'dimension'
-    }
-  }
-};
-```
+Tokens use `var()` references to maintain relationships across all layers:
 
-### 2. Build the tokens
-
-```bash
-yarn build
+```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);
+}
 ```
 
-### 3. Verify the output
-
-Check the generated files in `build/base/` and `build/semantic/` to ensure your tokens are correctly transformed.
-
-## Build Architecture
+#### Benefits of This Approach
 
-The build system separates tokens into three categories:
+- **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
 
-### Global Tokens
-- Shared across all brands
-- Responsive breakpoints, accessibility values
-- Output: `build/globals/`
-- Available for reference by brand tokens
-
-### Base Tokens
-- Default foundation values (colors, spacing, fonts, borders)
-- No component-specific tokens
-- Output: `build/base/`
-- Used as references by semantic tokens
-
-### Semantic Tokens
-- Component and context-specific tokens
-- Reference base and global tokens for values
-- Output: `build/semantic/`
-- **CSS format uses `var()` references** - maintains relationships with base tokens
-- **JS/JSON formats use resolved values** - self-contained for programmatic use
+#### Using Only Base Tokens
 
-### Brand-Specific Tokens (Optional)
-- Custom brand overrides can be added to `src/tokens/brands/{brand}/`
-- Automatically detected and built to `build/{brand}/base/` and `build/{brand}/semantic/`
-- Follow the same structure as default tokens
+If you only need base tokens (colors, spacing, fonts) without semantic tokens, you can import just the base and global files:
 
-### Reference Behavior
-
-**CSS Output:**
 ```css
-/* Semantic tokens reference base tokens */
---button-primary-background: var(--color-gray-black);
-```
-
-**JavaScript/JSON Output:**
-```javascript
-// Semantic tokens contain resolved values
-export const buttonPrimaryBackground = "hsl(0, 0%, 0%)";
+@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);
+}
 ```
 
-## Available Transforms
-
-The build system uses transforms that:
-- **Remove the 'brand' keyword** from token paths for cleaner names
-- **Convert colors** - Uses `color/hsl` for CSS and JS/JSON
-- **Maintain sizes in rem units** - Using the `size/rem` transform
-- **Apply naming conventions** per platform:
-  - **CSS:** kebab-case (`--color-tatari-red`)
-  - **JavaScript:** camelCase (`colorTatariRed`)
-  - **JSON:** kebab-case nested structure
-
-### Custom Transforms
-
-Located in `src/transforms/`:
-- `name-kebab-no-brand.js` - Converts names to kebab-case and removes 'brand' from path
-- `name-camel-no-brand.js` - Converts names to camelCase and removes 'brand' from path
-
-## Available Filters
+**Note:** Base tokens may reference global tokens (like accessibility values), so it's recommended to include globals even when not using semantic tokens.
 
-Custom filters control which tokens are included in each build:
+### Using JavaScript/TypeScript Tokens
 
-### brand-only
-Filters tokens to exclude global tokens from brand builds. This ensures:
-- Global tokens are available for references in brand tokens
-- Brand builds contain only brand-specific tokens
-- Clean separation between global and brand-specific layers
+JavaScript and JSON formats output resolved values, so semantic tokens can be used independently:
 
-### semantic-only
-Filters tokens to include only those defined in the `semantic/` directory. This ensures:
-- Base tokens are available for references (CSS uses `var()`, JS/JSON resolve values)
-- Semantic build contains only component-specific tokens
-- Clean separation between foundation and application layers
-
-Located in `src/filters/`:
-- `brand-only.js`
-- `semantic-only.js`
-
-## Adding a New Brand
-
-1. Create a new brand directory:
-```bash
-mkdir -p src/tokens/brands/{brand-name}
-mkdir -p src/tokens/brands/{brand-name}/semantic
-```
-
-2. Add base token files (color.js, font.js, spacing.js, etc.) in the brand directory
-
-3. Add semantic token files in the semantic subdirectory
+```javascript
+// Semantic tokens contain resolved values
+import { buttonPrimaryBackground, buttonPrimaryText } from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';
 
-4. Build the tokens (brands are automatically detected):
-```bash
-yarn build
+const button = {
+  backgroundColor: buttonPrimaryBackground, // "hsl(0, 0%, 0%)"
+  color: buttonPrimaryText // "hsl(0, 0%, 100%)"
+};
 ```
 
-The build system will automatically detect and build all brands in `src/tokens/brands/`, generating output at `build/{brand-name}/base/` and `build/{brand-name}/semantic/`.
+#### Importing Base Tokens
 
-## Project Structure
+```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"
+};
 ```
-design-tokens/
-├── .changeset/             # Changeset files for version management
-├── build/                  # Generated output files (git-ignored)
-│   ├── globals/            # Global tokens output
-│   │   ├── variables.css
-│   │   ├── tokens.es6.js
-│   │   └── tokens.json
-│   ├── base/               # Default base tokens output
-│   │   ├── variables.css
-│   │   ├── tokens.es6.js
-│   │   └── tokens.json
-│   └── semantic/           # Default semantic tokens output
-│       ├── variables.css
-│       ├── tokens.es6.js
-│       └── tokens.json
-├── src/                    # Source files
-│   ├── tokens/             # Token definitions
-│   │   ├── base/           # Default base tokens
-│   │   │   ├── color.js
-│   │   │   ├── font.js
-│   │   │   ├── spacing.js
-│   │   │   └── border.js
-│   │   ├── semantic/       # Default semantic tokens
-│   │   │   ├── color.js
-│   │   │   ├── typography.js
-│   │   │   └── button.js
-│   │   ├── brands/         # Optional brand overrides (empty by default)
-│   │   └── globals/        # Global tokens
-│   │       ├── breakpoints.js
-│   │       └── a11y.js
-│   ├── transforms/         # Custom transforms
-│   │   ├── name-kebab-no-brand.js
-│   │   ├── name-camel-no-brand.js
-│   │   └── index.js
-│   └── filters/            # Custom filters
-│       ├── brand-only.js
-│       ├── semantic-only.js
-│       └── index.js
-├── build.js                # Style Dictionary configuration
-├── package.json
-├── CHANGELOG.md            # Auto-generated changelog
-├── USAGE.md                # Usage documentation (included in npm package)
-└── README.md               # This file (development documentation)
-```
-
-## Scripts
-
-- `yarn build` - Build all design tokens
-- `yarn clean` - Remove all generated files
-- `yarn prepublishOnly` - Clean and rebuild before publishing to npm
-- `yarn changeset` - Create a new changeset to document your changes
-- `yarn version` - Apply changesets and update version/changelog
-- `yarn release` - Publish updated packages to npm
-
-## Configuration
-
-### build.js
-
-The build configuration defines:
-- **Transform groups** - Collections of transforms for each output format (CSS, JS, JSON)
-- **Platform configs** - Output format specifications and file destinations
-- **Filter application** - Which tokens to include in each build
-- **Reference handling** - CSS uses `outputReferences: true` to preserve token relationships
 
-Key functions:
-- `getGlobalsTokensConfig()` - Builds global tokens
-- `getDefaultBaseTokensConfig()` - Builds default base tokens
-- `getDefaultSemanticTokensConfig()` - Builds default semantic tokens
-- `getBaseTokensConfig(brand)` - Builds brand-specific base tokens
-- `getSemanticTokensConfig(brand)` - Builds brand-specific semantic tokens
-- `getBrands()` - Automatically detects brands in `src/tokens/brands/`
+#### Importing Global Tokens
 
-## Dependencies
-
-- **style-dictionary** (^5.1.1) - Token transformation engine
-- **@changesets/cli** (^2.29.7) - Version management and changelog generation
-
-## Release Management
-
-This package uses [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs.
-
-### Creating a Changeset
-
-When making changes, create a changeset to document them:
+```javascript
+import { breakpointMedium, a11yMinTouchTarget } from '@beam-ui/design-tokens/build/globals/tokens.es6.js';
 
-```bash
-yarn changeset
+const config = {
+  breakpoint: breakpointMedium, // "768px"
+  minTouchSize: a11yMinTouchTarget // "40px"
+};
 ```
 
-Select the change type (`patch`, `minor`, or `major`) and describe your changes. The changeset file will be created in `.changeset/` and should be committed with your changes.
+### Using JSON Tokens
 
-### Versioning and Publishing
+JSON format provides a nested structure:
 
-For maintainers:
-
-```bash
-# Update version and changelog
-yarn version
+```javascript
+import tokens from '@beam-ui/design-tokens/build/semantic/tokens.json';
 
-# Publish to npm
-yarn release
+console.log(tokens.button.primary.background); // "hsl(0, 0%, 0%)"
+console.log(tokens.color.background.primary); // "hsl(0, 0%, 100%)"
 ```
 
-## Contributing
+## Token Reference
 
-When adding or modifying tokens:
+### Global Tokens
 
-1. **Use semantic naming** that describes the purpose, not the value
-   - ✅ `button-primary-background`
-   - ❌ `button-black-bg`
+**Breakpoints**
+- `breakpoint-small`, `breakpoint-medium`, `breakpoint-large`, `breakpoint-x-large`
 
-2. **Follow the existing token structure** and format
-   - Include both `value` and `type` properties
-   - Use single quotes for consistency
+**Accessibility**
+- `a11y-min-touch-target` - Minimum touch target size for interactive elements
 
-3. **Use token references** in semantic tokens
-   - Reference base tokens: `value: '{color.gray.black}'`
-   - Don't duplicate values in semantic tokens
+### Base Tokens
 
-4. **Test the build output** before committing
-   - Run `yarn build`
-   - Verify CSS, JS, and JSON outputs
-   - Check that references work correctly in CSS
+**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`
 
-5. **Create a changeset** to document your changes
-   - Run `yarn changeset`
-   - Describe what changed and why
+**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`
 
-6. **Document new token categories** if adding new types
+**Spacing**
+- `spacing-xx-small` through `spacing-xxx-large`
 
-7. **Color format requirements:**
-   - Use comma-based syntax for colors with alpha: `hsla(0, 0%, 0%, 0.3)`
-   - Space-separated syntax is fine for colors without alpha: `hsl(0 0% 0%)`
+**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`
 
-## Troubleshooting
+### Semantic Tokens
 
-### Issue: CSS variables show `undefined`
-**Solution:** Ensure you import files in the correct order (globals → base → semantic)
+**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)
 
-### Issue: Alpha channel gets stripped from colors
-**Solution:** Use comma-based color syntax (`hsla(0, 0%, 0%, 0.3)`) not slash syntax
+```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);
+}
+```
 
-### Issue: Semantic tokens don't update when base tokens change
-**Solution:** Check that semantic tokens use references (`{color.gray.black}`) not literal values
+### 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>
+  );
+};
+```
 
 ## License
 
-MIT
-
-## Related Documentation
+MIT License - see [LICENSE](./LICENSE) file for details
 
-- [USAGE.md](./USAGE.md) - Package usage and consumption guide
-- [Style Dictionary Documentation](https://styledictionary.com/)
-- [Design Tokens W3C Community Group](https://www.w3.org/community/design-tokens/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beam-ui/design-tokens",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A collection of design decisions and other artifacts for the Beam UI Design System",
   "type": "module",
   "main": "./build/base/tokens.es6.js",
@@ -10,7 +10,7 @@
   },
   "files": [
     "build",
-    "USAGE.md",
+    "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

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
-