npm - @marioschmidt/design-system-components - Versions diffs - 1.0.70 → 1.0.71 - Mend

@marioschmidt/design-system-components 1.0.70 → 1.0.71

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (193) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,30 @@
-# @marioschmidt/design-system-components
+# 🧩 BILD Design System Components
-BILD Design System Web Components - Stencil-based component library that consumes design tokens.
+> **Part of the [BILD Design Ops Pipeline](../../README.md)** | [Token Documentation](../tokens/README.md) | [Icon Documentation](../icons/README.md)
-## Installation
+Stencil-based Web Components for the BILD Design System. Components consume design tokens via CSS Custom Properties and work in any framework.
+[![npm version](https://img.shields.io/npm/v/@marioschmidt/design-system-components.svg)](https://www.npmjs.com/package/@marioschmidt/design-system-components)
+[![Build Status](https://github.com/UXWizard25/vv-token-test-v3/workflows/Build%20Design%20Tokens/badge.svg)](https://github.com/UXWizard25/vv-token-test-v3/actions)
+---
+## 📋 Table of Contents
+- [📦 Installation](#-installation)
+- [🚀 Usage](#-usage)
+- [🧩 Available Components](#-available-components)
+- [🎨 Theming](#-theming)
+- [🌓 Shadow DOM](#-shadow-dom)
+- [📁 Project Structure](#-project-structure)
+- [⚙️ Development](#️-development)
+- [📚 Storybook](#-storybook)
+- [🔗 Related](#-related)
+- [📄 License](#-license)
+---
+## 📦 Installation
 ```bash
 npm install @marioschmidt/design-system-components
@@ -14,7 +36,9 @@ npm install @marioschmidt/design-system-components
 npm install @marioschmidt/design-system-tokens @marioschmidt/design-system-components
 ```
-## Usage
+---
+## 🚀 Usage
 ### Option 1: Lazy Loading (Recommended)
@@ -38,7 +62,7 @@ import '@marioschmidt/design-system-components/components';
 import { DsButton, DsCard } from '@marioschmidt/design-system-components';
 ```
-## HTML Usage
+### HTML Usage
 ```html
 <!DOCTYPE html>
@@ -63,35 +87,46 @@ import { DsButton, DsCard } from '@marioschmidt/design-system-components';
 </html>
 ```
-## Available Components
+---
-| Component | Tag | Description |
-|-----------|-----|-------------|
-| Button | `<ds-button>` | Primary, secondary, ghost variants |
-| Card | `<ds-card>` | Content container with styling |
+## 🧩 Available Components
-## Brand Switching
+| Component | Tag | Variants | Description |
+|-----------|-----|----------|-------------|
+| **Button** | `<ds-button>` | `primary`, `secondary`, `ghost` | Interactive button with hover/active states |
+| **Card** | `<ds-card>` | - | Content container with shadow and padding |
-Components automatically adapt to brand/theme changes via CSS Custom Properties:
+### Button
 ```html
-<!-- BILD Brand -->
-<body data-color-brand="bild" data-content-brand="bild" data-theme="light">
-  <ds-button variant="primary">BILD Button</ds-button>
-</body>
+<!-- Primary (default) -->
+<ds-button variant="primary">Primary Button</ds-button>
-<!-- SportBILD Brand -->
-<body data-color-brand="sportbild" data-content-brand="sportbild" data-theme="dark">
-  <ds-button variant="primary">Sport Button</ds-button>
-</body>
+<!-- Secondary -->
+<ds-button variant="secondary">Secondary Button</ds-button>
-<!-- Advertorial in BILD context -->
-<body data-color-brand="bild" data-content-brand="advertorial" data-theme="light">
-  <ds-button variant="primary">Advertorial Button</ds-button>
-</body>
+<!-- Ghost -->
+<ds-button variant="ghost">Ghost Button</ds-button>
+```
+### Card
+```html
+<ds-card>
+  <h2>Card Title</h2>
+  <p>Card content with automatic styling.</p>
+</ds-card>
 ```
-## Data Attributes
+---
+## 🎨 Theming
+Components automatically adapt to brand/theme/density changes via CSS Custom Properties.
+### Data Attributes
+Set these on `<body>` or any parent element:
 | Attribute | Values | Purpose |
 |-----------|--------|---------|
@@ -100,7 +135,36 @@ Components automatically adapt to brand/theme changes via CSS Custom Properties:
 | `data-theme` | `light`, `dark` | Color mode |
 | `data-density` | `default`, `dense`, `spacious` | Spacing density |
-## Shadow DOM
+### Brand Examples
+```html
+<!-- BILD Brand (Light) -->
+<body data-color-brand="bild" data-content-brand="bild" data-theme="light" data-density="default">
+  <ds-button variant="primary">BILD Button</ds-button>  <!-- Red -->
+</body>
+<!-- SportBILD Brand (Dark, Dense) -->
+<body data-color-brand="sportbild" data-content-brand="sportbild" data-theme="dark" data-density="dense">
+  <ds-button variant="primary">Sport Button</ds-button>  <!-- Blue -->
+</body>
+<!-- Advertorial in BILD context -->
+<body data-color-brand="bild" data-content-brand="advertorial" data-theme="light">
+  <ds-button variant="primary">Advertorial Button</ds-button>  <!-- BILD colors, Advertorial typography -->
+</body>
+```
+### Runtime Switching
+```javascript
+// Switch brand at runtime - components update automatically!
+document.body.dataset.colorBrand = 'sportbild';
+document.body.dataset.theme = 'dark';
+```
+---
+## 🌓 Shadow DOM
 All components use Shadow DOM for style encapsulation. Design tokens are inherited through CSS Custom Properties:
@@ -111,38 +175,212 @@ Light DOM                          Shadow DOM
   │                                  #shadow-root
   │  CSS Variables set here:           .button {
   │  --button-primary-bg: #DD0000      background: var(--button-primary-bg);
+  │  --button-label-color: #FFF        color: var(--button-label-color);
   │                                    /* Inherits from body! */
   └────────────────────────────►     }
+       Variables inherit
+       through Shadow DOM
 ```
-## TypeScript
+### How It Works
-Full TypeScript support with type definitions:
+1. **Token CSS** is loaded in the Light DOM (on `<body>` or `<html>`)
+2. **CSS Custom Properties inherit** through the Shadow DOM boundary
+3. **Components read tokens** using `var(--token-name)`
+4. **No JavaScript needed** for theming - pure CSS inheritance
-```typescript
-import type { Components } from '@marioschmidt/design-system-components';
+### What Inherits
+| Token Type | Inheritance | Example |
+|------------|-------------|---------|
+| Color tokens | ✅ Inherits | `var(--button-primary-bg-color)` |
+| Spacing tokens | ✅ Inherits | `var(--button-inline-space)` |
+| Typography tokens | ✅ Inherits | `var(--button-label-font-size)` |
+| Effects (shadows) | ✅ Inherits | `var(--shadow-soft-md)` |
+---
+## 📁 Project Structure
-const button: Components.DsButton = document.querySelector('ds-button');
-button.variant = 'primary';
+```
+packages/components/
+├── src/                          # Stencil component source
+│   ├── ds-button/
+│   │   ├── ds-button.tsx         # Component logic
+│   │   ├── ds-button.css         # Component styles (uses tokens)
+│   │   └── ds-button.stories.ts  # Storybook stories
+│   ├── ds-card/
+│   │   ├── ds-card.tsx
+│   │   ├── ds-card.css
+│   │   └── ds-card.stories.ts
+│   └── components.d.ts           # Generated type definitions
+│
+├── docs/                         # Storybook MDX documentation
+│   ├── intro.mdx                 # Introduction & overview
+│   ├── colors.mdx                # Color tokens
+│   ├── typography.mdx            # Typography tokens
+│   ├── spacing.mdx               # Spacing & density
+│   └── effects.mdx               # Shadows & effects
+│
+├── dist/                         # Built output (gitignored)
+│   ├── esm/                      # ES Modules
+│   ├── cjs/                      # CommonJS
+│   ├── components/               # Custom Elements (auto-define)
+│   ├── loader/                   # Lazy loader
+│   └── types/                    # TypeScript definitions
+│
+├── package.json
+└── README.md
+```
+---
+## ⚙️ Development
+### Prerequisites
+Build tokens first (components depend on token CSS):
+```bash
+npm run build:tokens
 ```
-## Peer Dependencies
+### Commands
-- `@marioschmidt/design-system-tokens` (optional but recommended)
+```bash
+# Start dev server with hot reload
+npm run dev:stencil        # Port 3333
+# Build components
+npm run build:components
+# Build everything (tokens + icons + components)
+npm run build:all
+# Clean build output
+npm run clean
+```
-## Development
+### Creating New Components
+1. **Create component directory:**
+   ```
+   packages/components/src/ds-{name}/
+   ├── ds-{name}.tsx
+   ├── ds-{name}.css
+   └── ds-{name}.stories.ts
+   ```
+2. **Component structure:**
+   ```tsx
+   import { Component, Prop, h } from '@stencil/core';
+   @Component({
+     tag: 'ds-{name}',
+     styleUrl: 'ds-{name}.css',
+     shadow: true,
+   })
+   export class Ds{Name} {
+     @Prop() variant: string = 'default';
+     render() {
+       return (
+         <div class={`ds-{name} ds-{name}--${this.variant}`}>
+           <slot></slot>
+         </div>
+       );
+     }
+   }
+   ```
+3. **Use design tokens in CSS:**
+   ```css
+   :host {
+     display: block;
+   }
+   .ds-{name} {
+     /* Tokens inherit from Light DOM automatically */
+     background: var(--surface-color-primary);
+     color: var(--text-color-primary);
+     padding: var(--space-2-x);
+     border-radius: var(--border-radius-md);
+   }
+   ```
+---
+## 📚 Storybook
+Interactive component documentation with live theming.
 ```bash
-# In monorepo root
-npm run dev:stencil    # Start dev server (port 3333)
-npm run storybook      # Start Storybook (port 6006)
+npm run storybook          # Start dev server (port 6006)
+npm run build:storybook    # Build static site
+```
+### Features
+- **4-Axis Controls**: Color Brand, Content Brand, Theme, Density
+- **Component Stories**: All variants with controls
+- **Styleguide Pages**: Colors, Typography, Spacing, Effects
+- **Dark Mode Toggle**: Synced with design tokens
+### Writing Stories
+```typescript
+// ds-button.stories.ts
+import type { Meta, StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+const meta: Meta = {
+  title: 'Components/Button',
+  tags: ['autodocs'],
+  render: (args) => html`
+    <ds-button variant=${args.variant}>
+      ${args.label}
+    </ds-button>
+  `,
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost'],
+    },
+  },
+};
+export default meta;
+export const Primary: StoryObj = {
+  args: { variant: 'primary', label: 'Click me' },
+};
 ```
-## Related Packages
+---
+## 🔗 Related
-- [@marioschmidt/design-system-tokens](https://www.npmjs.com/package/@marioschmidt/design-system-tokens) - Design tokens
-- [@marioschmidt/design-system-icons](https://www.npmjs.com/package/@marioschmidt/design-system-icons) - Icon library
+| Document | Description |
+|----------|-------------|
+| [📖 Main README](../../README.md) | Project overview |
+| [📖 Tokens README](../tokens/README.md) | Design tokens documentation |
+| [📖 Icons README](../icons/README.md) | Icon library documentation |
+| [📖 CSS Documentation](../tokens/docs/css.md) | CSS Custom Properties & Shadow DOM |
-## License
+---
+## 📄 License
 MIT
+---
+**Built with ❤️ for the BILD Design System**
+| Feature | Status |
+|---------|--------|
+| Shadow DOM | ✅ |
+| CSS Custom Properties | ✅ |
+| 4-Axis Theming | ✅ |
+| TypeScript | ✅ |
+| Storybook | ✅ |