@marioschmidt/design-system-tokens 1.0.69 → 1.0.71

package/{dist/stencil/www/css/README.md → docs/css.md}

@@ -1,28 +1,29 @@
-# CSS - Design System Tokens
+# 🌐 CSS - Design System Tokens
 
-> **CSS Custom Properties für Web-Anwendungen**
+> **CSS Custom Properties for Web Applications**
 >
-> Dual-Axis Architektur, responsive, multi-brand ready.
+> Responsive, multi-brand ready with **Dual-Axis Architecture**.
 
 ---
 
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Dual-Axis Architecture](#dual-axis-architecture)
-- [File Structure](#file-structure)
-- [Naming Conventions](#naming-conventions)
-- [Data Attributes](#data-attributes)
-- [Bundle Options](#bundle-options)
-- [Token Categories](#token-categories)
-- [Responsive Tokens](#responsive-tokens)
-- [Component Tokens](#component-tokens)
-- [Typography & Effects](#typography--effects)
-- [Usage Examples](#usage-examples)
+## 📋 Table of Contents
+
+- [🚀 Quick Start](#-quick-start)
+- [🔀 Dual-Axis Architecture](#-dual-axis-architecture)
+- [📁 File Structure](#-file-structure)
+- [📝 Naming Conventions](#-naming-conventions)
+- [🏷️ Data Attributes](#️-data-attributes)
+- [📦 Bundle Options](#-bundle-options)
+- [🎨 Token Categories](#-token-categories)
+- [📱 Responsive Tokens](#-responsive-tokens)
+- [🧩 Component Tokens](#-component-tokens)
+- [✍️ Typography & Effects](#️-typography--effects)
+- [💡 Usage Examples](#-usage-examples)
+- [📚 Storybook](#-storybook)
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ### 1. HTML Setup
 
@@ -80,7 +81,7 @@ document.documentElement.dataset.contentBrand = 'advertorial';
 
 ---
 
-## Dual-Axis Architecture
+## 🔀 Dual-Axis Architecture
 
 The CSS output uses a **Dual-Axis Architecture** to separate concerns:
 
@@ -121,7 +122,7 @@ The CSS output uses a **Dual-Axis Architecture** to separate concerns:
 
 ---
 
-## File Structure
+## 📁 File Structure
 
 ```
 dist/css/
@@ -153,7 +154,7 @@ dist/css/
 
 ---
 
-## Naming Conventions
+## 📝 Naming Conventions
 
 CSS tokens use **kebab-case** with hyphen separation before AND after numbers:
 
@@ -169,7 +170,7 @@ CSS tokens use **kebab-case** with hyphen separation before AND after numbers:
 
 ---
 
-## Data Attributes
+## 🏷️ Data Attributes
 
 ### Required Attributes
 
@@ -204,7 +205,7 @@ CSS tokens use **kebab-case** with hyphen separation before AND after numbers:
 
 ---
 
-## Bundle Options
+## 📦 Bundle Options
 
 ### Option A: All-in-One Bundle
 
@@ -243,7 +244,7 @@ Best for: Using only semantic tokens, no component tokens.
 
 ---
 
-## Token Categories
+## 🎨 Token Categories
 
 ### 1. Primitives (shared/primitives.css)
 
@@ -346,7 +347,7 @@ Component-specific design decisions. Uses both axes.
 
 ---
 
-## Responsive Tokens
+## 📱 Responsive Tokens
 
 ### Breakpoints
 
@@ -379,7 +380,7 @@ Tokens only appear in media queries when values change:
 
 ---
 
-## Component Tokens
+## 🧩 Component Tokens
 
 ### Structure per Component
 
@@ -422,7 +423,7 @@ Each component file contains:
 
 ---
 
-## Typography & Effects
+## ✍️ Typography & Effects
 
 ### Typography Classes
 
@@ -470,7 +471,7 @@ Usage:
 
 ---
 
-## Usage Examples
+## 💡 Usage Examples
 
 ### Standard BILD App
 
@@ -548,7 +549,7 @@ setDensity('spacious'); // Generous spacing
 
 ---
 
-## Shadow DOM / Web Components
+## 🕸️ Shadow DOM / Web Components
 
 The CSS output is **Shadow DOM compatible** for use with frameworks like **Stencil**, **Lit**, or native Web Components.
 
@@ -708,11 +709,105 @@ src/components/
   index.html              # Dev/test page with brand switcher
 ```
 
-> See [CLAUDE.md](../CLAUDE.md#stencil-web-components-integration) for complete Stencil documentation.
+> See [CLAUDE.md](../../CLAUDE.md#stencil-web-components-integration) for complete Stencil documentation.
+
+---
+
+## 📚 Storybook
+
+The design system includes a **Storybook 8.x** setup for component development and documentation with full 4-axis token support.
+
+### Quick Start
+
+```bash
+# Build tokens first (required)
+npm run build
+
+# Start Storybook dev server (port 6006)
+npm run storybook
+
+# Build static Storybook site
+npm run build:storybook
+```
+
+### Features
+
+**4-Axis Token Switching in Toolbar:**
+
+| Toolbar Control | Options | Description |
+|-----------------|---------|-------------|
+| Color Brand | BILD, SportBILD | Colors + effects axis |
+| Content Brand | BILD, SportBILD, Advertorial | Typography + sizing axis |
+| Dark Mode Toggle (🌙) | Light, Dark | Unified UI + content theming |
+| Density | Default, Dense, Spacious | Spacing density |
+
+### Dark Mode Integration
+
+The `storybook-dark-mode` addon provides unified dark mode:
+
+- **Moon icon (🌙)** in toolbar toggles both Storybook UI and content area
+- Design tokens (`data-theme`) sync automatically via localStorage polling
+- Custom BILD themes match the design system look
+
+### Writing Stories
+
+```typescript
+// src/components/ds-button/ds-button.stories.ts
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+import './ds-button';
+
+const meta: Meta = {
+  title: 'Components/Button',
+  component: 'ds-button',
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'tertiary'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Primary: Story = {
+  args: { variant: 'primary' },
+  render: (args) => html`
+    <ds-button variant=${args.variant}>Primary Button</ds-button>
+  `,
+};
+```
+
+### Styleguide Documentation
+
+The `src/docs/` directory contains visual documentation pages for design system foundations:
+
+| Page | File | Description |
+|------|------|-------------|
+| Introduction | `intro.mdx` | Overview, brand architecture, links |
+| Colors | `colors.mdx` | Color palettes with visual swatches |
+| Typography | `typography.mdx` | Font families, weights, text styles |
+| Spacing | `spacing.mdx` | Spacing scale, density modes |
+| Effects | `effects.mdx` | Shadow tokens with live previews |
+
+These pages use MDX with `@storybook/blocks` and include styled visual elements like color swatches, spacing bars, and shadow cards.
+
+### Configuration
+
+| File | Purpose |
+|------|---------|
+| `build-config/storybook/main.ts` | Framework, addons, static dirs |
+| `build-config/storybook/preview.ts` | Decorators, toolbar controls |
+| `build-config/storybook/preview-body.html` | Dark mode sync script |
+| `build-config/storybook/manager.ts` | Custom BILD UI themes |
+
+> See [CLAUDE.md](../../CLAUDE.md#storybook-integration) for complete Storybook documentation.
 
 ---
 
-## Browser Support
+## 🌐 Browser Support
 
 CSS Custom Properties are supported in all modern browsers:
 
@@ -730,9 +825,13 @@ For legacy browser support, fallback values are included:
 
 ---
 
-## Related Documentation
+## 📖 Related Documentation
 
-- [JavaScript/React Tokens](./js.md)
-- [Android Compose Tokens](./android.md)
-- [iOS SwiftUI Tokens](./ios.md)
-- [Architecture Overview](../CLAUDE.md)
+| Document | Description |
+|----------|-------------|
+| [JavaScript/React](./js.md) | ESM tokens with React ThemeProvider |
+| [Android Compose](./android.md) | Kotlin tokens for Jetpack Compose |
+| [iOS SwiftUI](./ios.md) | Swift tokens for SwiftUI |
+| [Tokens README](../README.md) | Token pipeline overview |
+| [Main README](../../README.md) | Project overview |
+| [CLAUDE.md](../../CLAUDE.md) | Architecture & build details |