@beam-ui/design-tokens 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @beam-ui/design-tokens
+
+## 1.0.0
+
+### Major Changes
+
+- The first major version release with all the initial base and semantic tokens
+
+## 0.0.2
+
+### Patch Changes
+
+- 7de247c: The initial project structure in preparation for the release

package/README.md

@@ -0,0 +1,394 @@
+# 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).
+
+## 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.
+
+## Installation
+
+```bash
+# Install dependencies
+yarn install
+```
+
+## Building Tokens
+
+To build the design tokens into all output formats:
+
+```bash
+yarn build
+```
+
+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)
+
+## Token Structure
+
+### Source Organization
+
+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.)
+
+#### 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
+
+#### 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.)
+
+#### Brand-Specific Tokens (`src/tokens/brands/{brand}/`)
+Optional brand overrides following the same base/semantic structure
+
+### Token Format
+
+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.)
+
+**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'
+      }
+    }
+  }
+};
+```
+
+**Example - Semantic Token (with references):**
+```javascript
+export default {
+  button: {
+    primary: {
+      background: {
+        value: '{color.gray.black}', // References base token
+        type: 'color'
+      }
+    }
+  }
+};
+```
+
+**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)'
+```
+
+## Adding New Tokens
+
+### 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'
+    }
+  }
+};
+```
+
+### 2. Build the tokens
+
+```bash
+yarn build
+```
+
+### 3. Verify the output
+
+Check the generated files in `build/base/` and `build/semantic/` to ensure your tokens are correctly transformed.
+
+## Build Architecture
+
+The build system separates tokens into three categories:
+
+### 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
+
+### 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
+
+### 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%)";
+```
+
+## 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
+
+Custom filters control which tokens are included in each build:
+
+### 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
+
+### 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
+
+4. Build the tokens (brands are automatically detected):
+```bash
+yarn build
+```
+
+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/`.
+
+## Project Structure
+
+```
+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/`
+
+## 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:
+
+```bash
+yarn changeset
+```
+
+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.
+
+### Versioning and Publishing
+
+For maintainers:
+
+```bash
+# Update version and changelog
+yarn version
+
+# Publish to npm
+yarn release
+```
+
+## Contributing
+
+When adding or modifying tokens:
+
+1. **Use semantic naming** that describes the purpose, not the value
+   - ✅ `button-primary-background`
+   - ❌ `button-black-bg`
+
+2. **Follow the existing token structure** and format
+   - Include both `value` and `type` properties
+   - Use single quotes for consistency
+
+3. **Use token references** in semantic tokens
+   - Reference base tokens: `value: '{color.gray.black}'`
+   - Don't duplicate values in semantic tokens
+
+4. **Test the build output** before committing
+   - Run `yarn build`
+   - Verify CSS, JS, and JSON outputs
+   - Check that references work correctly in CSS
+
+5. **Create a changeset** to document your changes
+   - Run `yarn changeset`
+   - Describe what changed and why
+
+6. **Document new token categories** if adding new types
+
+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%)`
+
+## Troubleshooting
+
+### Issue: CSS variables show `undefined`
+**Solution:** Ensure you import files in the correct order (globals → base → semantic)
+
+### Issue: Alpha channel gets stripped from colors
+**Solution:** Use comma-based color syntax (`hsla(0, 0%, 0%, 0.3)`) not slash syntax
+
+### Issue: Semantic tokens don't update when base tokens change
+**Solution:** Check that semantic tokens use references (`{color.gray.black}`) not literal values
+
+## License
+
+MIT
+
+## Related Documentation
+
+- [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/USAGE.md

@@ -0,0 +1,286 @@
+# 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
+