🧩 BILD Design System Components

> Part of the BILD Design Ops Pipeline | Token Documentation | Icon Documentation

Stencil-based Web Components for the BILD Design System. Components consume design tokens via CSS Custom Properties and work in any framework.

Framework-specific wrappers available:
- React Wrappers - @marioschmidt/design-system-react
- Vue 3 Wrappers - @marioschmidt/design-system-vue

These wrappers are co-located in the same packages/components/ directory as they are tightly coupled to the core Stencil components.

![npm version](https://www.npmjs.com/package/@marioschmidt/design-system-components)
![Build Status](https://github.com/UXWizard25/bild-design-system/actions)

---

📋 Table of Contents

- 📦 Installation
- 🚀 Usage
- ⚛️ React & Vue
- 🧩 Available Components
- 🎨 Theming
- 🌓 Shadow DOM
- 📁 Project Structure
- ⚙️ Development
- 📚 Storybook
- 🔗 Related
- 📄 License

---

📦 Installation

``bash npm install @marioschmidt/design-system-components`

Recommended: Install together with design tokens:

`bash npm install @marioschmidt/design-system-tokens @marioschmidt/design-system-components`

---

`🚀 Usage`

`$3`

`javascript import { defineCustomElements } from '@marioschmidt/design-system-components/loader';

// Register all components (lazy-loaded on first use) defineCustomElements();`

`$3`

`javascript // Import and auto-register all components import '@marioschmidt/design-system-components/components';`

`$3`

`javascript import { DsButton, DsCard } from '@marioschmidt/design-system-components';`

`$3`

`html

Click me

`Card Title`


    Card content goes here.

---

`⚛️ React & Vue`

For better framework integration, use our auto-generated wrapper packages:

`$3`

`bash npm install @marioschmidt/design-system-react`

`tsx import { DsButton, DsCard } from '@marioschmidt/design-system-react'; import '@marioschmidt/design-system-tokens/css/bundles/bild.css';

function App() { return (


       console.log('clicked')}>
        Click me


  );
}


📖 Full React Documentation
$3

`bash npm install @marioschmidt/design-system-vue`

`vue

📖 Full Vue Documentation

---

`🧩 Available Components`

| Component | Tag | Variants | Description | |-----------|-----|----------|-------------| | Button | | primary, secondary, ghost| Interactive button with hover/active states | | Card | | - | Content container with shadow and padding |

`$3`

`html Primary Button

Secondary Button

Ghost Button`

`$3`

`html

`Card Title`


  Card content with automatic styling.


---
🎨 Theming
Components automatically adapt to brand/theme/density changes via CSS Custom Properties.
$3

Set these on or any parent element:

| Attribute | Values | Purpose | |-----------|--------|---------| |data-color-brand | bild, sportbild| Colors & effects | |data-content-brand | bild, sportbild, advertorial| Typography & spacing | |data-theme | light, dark| Color mode | |data-density | default, dense, spacious | Spacing density |

`$3`

`html BILD Button

Sport Button

Advertorial Button`

`$3`

`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:

`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`

`$3`

1. Token CSS is loaded in the Light DOM (on or ) 2. CSS Custom Properties inherit through the Shadow DOM boundary 3. Components read tokens usingvar(--token-name)4. No JavaScript needed for theming - pure CSS inheritance

`$3`

| 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`

`apps/ └── docs/ # @bild/docs (Storybook documentation) ├── package.json # Isolated Storybook dependencies └── stories/ └── foundations/ # Auto-generated foundation docs ├── intro.mdx # Introduction (manual) ├── colors.mdx # Color tokens (auto-generated) ├── typography.mdx # Typography (auto-generated) ├── spacing.mdx # Spacing & density (auto-generated) └── effects.mdx # Shadows & effects (auto-generated)

packages/components/ ├── core/ # This package (@marioschmidt/design-system-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/ │ │ │ └── ... │ │ └── components.d.ts # Generated type definitions │ │ │ ├── dist/ # Built output (gitignored) │ │ ├── esm/ # ES Modules │ │ ├── cjs/ # CommonJS │ │ ├── components/ # Custom Elements (auto-define) │ │ ├── loader/ # Lazy loader │ │ └── types/ # TypeScript definitions │ │ │ ├── package.json │ └── README.md │ ├── react/ # @marioschmidt/design-system-react │ ├── src/ # Auto-generated React wrappers │ ├── dist/ # Built output │ └── README.md │ └── vue/ # @marioschmidt/design-system-vue ├── src/ # Auto-generated Vue wrappers ├── dist/ # Built output └── README.md`

---

`⚙️ Development`

`$3`

Build tokens first (components depend on token CSS):

`bash npm run build:tokens`

`$3`

`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

$3

1. Create component directory:`packages/components/core/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 (

ds-{name} ds-{name}--${this.variant}}>


       );
     }
   }
   `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
npm run storybook          # Start dev server (port 6006)
npm run build:storybook    # Build static site
npm run build:docs         # Regenerate foundation docs from tokens
`
$3
- 4-Axis Controls: Color Brand, Content Brand, Theme, Density
- Component Stories: All variants with controls
- Styleguide Pages: Colors, Typography, Spacing, Effects (auto-generated)
- Dark Mode Toggle: Synced with design tokens
$3
Foundation pages (Colors, Typography, Spacing, Effects) are automatically generated from token JSON files by scripts/tokens/generate-docs.js. This ensures documentation stays in sync with the actual token values.
`bash
Regenerate docs after token changes

npm run build:docs
`| Page | Source |
|------|--------|
| Colors | Semantic > Color tokens |
| Typography | Semantic > Typography tokens |
| Spacing | Semantic > Space tokens (Inline, Stack, Gap) |
| Effects | Semantic shadow tokens |
$3
`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
    
      ${args.label}
    
  ,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost'],
    },
  },
};
export default meta;
export const Primary: StoryObj = {
  args: { variant: 'primary', label: 'Click me' },
};
``
---
🔗 Related
| Document | Description |
|----------|-------------|
| 📖 Main README | Project overview |
| 📖 React Wrappers | React wrapper components |
| 📖 Vue Wrappers | Vue 3 wrapper components |
| 📖 Tokens README | Design tokens documentation |
| 📖 Icons README | Icon library documentation |
| 📖 CSS Documentation | CSS Custom Properties & Shadow DOM |
---
📄 License
MIT
---
Built with ❤️ for the BILD Design System
| Feature | Status |
|---------|--------|
| Shadow DOM | ✅ |
| CSS Custom Properties | ✅ |
| 4-Axis Theming | ✅ |
| TypeScript | ✅ |
| Storybook | ✅ |
| React Wrappers | ✅ |
| Vue 3 Wrappers | ✅ |

`🧩 BILD Design System Components`

> Part of the BILD Design Ops Pipeline | Token Documentation | Icon Documentation

Stencil-based Web Components for the BILD Design System. Components consume design tokens via CSS Custom Properties and work in any framework.

Framework-specific wrappers available: - React Wrappers - @marioschmidt/design-system-react - Vue 3 Wrappers - @marioschmidt/design-system-vue

These wrappers are co-located in the same packages/components/ directory as they are tightly coupled to the core Stencil components.

![npm version](https://www.npmjs.com/package/@marioschmidt/design-system-components) ![Build Status](https://github.com/UXWizard25/bild-design-system/actions)

---

`📋 Table of Contents`

- 📦 Installation - 🚀 Usage - ⚛️ React & Vue - 🧩 Available Components - 🎨 Theming - 🌓 Shadow DOM - 📁 Project Structure - ⚙️ Development - 📚 Storybook - 🔗 Related - 📄 License

---

`📦 Installation`

``bash npm install @marioschmidt/design-system-components `

Recommended: Install together with design tokens:

`bash npm install @marioschmidt/design-system-tokens @marioschmidt/design-system-components `

---

`🚀 Usage`

`$3`

`javascript import { defineCustomElements } from '@marioschmidt/design-system-components/loader';

// Register all components (lazy-loaded on first use) defineCustomElements(); `

`$3`

`javascript // Import and auto-register all components import '@marioschmidt/design-system-components/components'; `

`$3`

`javascript import { DsButton, DsCard } from '@marioschmidt/design-system-components'; `

`$3`

`html

Click me

`Card Title`


    Card content goes here.

  

`
---
⚛️ React & Vue
For better framework integration, use our auto-generated wrapper packages:
$3
`bash
npm install @marioschmidt/design-system-react
`
`tsx
import { DsButton, DsCard } from '@marioschmidt/design-system-react';
import '@marioschmidt/design-system-tokens/css/bundles/bild.css';
function App() {
  return (
    

       console.log('clicked')}>
        Click me
      
    

  );
}
`
📖 Full React Documentation
$3
`bash
npm install @marioschmidt/design-system-vue
`
`vue

`
📖 Full Vue Documentation
---
🧩 Available Components
| Component | Tag | Variants | Description |
|-----------|-----|----------|-------------|
| Button |  | primary, secondary, ghost | Interactive button with hover/active states |
| Card |  | - | Content container with shadow and padding |
$3
`html

Primary Button

Secondary Button

Ghost Button
`
$3
`html

  
Card Title

  Card content with automatic styling.


`
---
🎨 Theming
Components automatically adapt to brand/theme/density changes via CSS Custom Properties.
$3
Set these on  or any parent element:
| Attribute | Values | Purpose |
|-----------|--------|---------|
| data-color-brand | bild, sportbild | Colors & effects |
| data-content-brand | bild, sportbild, advertorial | Typography & spacing |
| data-theme | light, dark | Color mode |
| data-density | default, dense, spacious | Spacing density |
$3
`html


  BILD Button  


  Sport Button  


  Advertorial Button  

`
$3
`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:
`
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
`
$3
1. Token CSS is loaded in the Light DOM (on  or )
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
$3
| 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
`
apps/
└── docs/                         # @bild/docs (Storybook documentation)
    ├── package.json              # Isolated Storybook dependencies
    └── stories/
        └── foundations/          # Auto-generated foundation docs
            ├── intro.mdx         # Introduction (manual)
            ├── colors.mdx        # Color tokens (auto-generated)
            ├── typography.mdx    # Typography (auto-generated)
            ├── spacing.mdx       # Spacing & density (auto-generated)
            └── effects.mdx       # Shadows & effects (auto-generated)
packages/components/
├── core/                         # This package (@marioschmidt/design-system-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/
│   │   │   └── ...
│   │   └── components.d.ts       # Generated type definitions
│   │
│   ├── dist/                     # Built output (gitignored)
│   │   ├── esm/                  # ES Modules
│   │   ├── cjs/                  # CommonJS
│   │   ├── components/           # Custom Elements (auto-define)
│   │   ├── loader/               # Lazy loader
│   │   └── types/                # TypeScript definitions
│   │
│   ├── package.json
│   └── README.md
│
├── react/                        # @marioschmidt/design-system-react
│   ├── src/                      # Auto-generated React wrappers
│   ├── dist/                     # Built output
│   └── README.md
│
└── vue/                          # @marioschmidt/design-system-vue
    ├── src/                      # Auto-generated Vue wrappers
    ├── dist/                     # Built output
    └── README.md
`
---
⚙️ Development
$3
Build tokens first (components depend on token CSS):
`bash
npm run build:tokens
`
$3
`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
`
$3
1. Create component directory:
   `
   packages/components/core/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 (
         
ds-{name} ds-{name}--${this.variant}}>
           
         

       );
     }
   }
   `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
npm run storybook          # Start dev server (port 6006)
npm run build:storybook    # Build static site
npm run build:docs         # Regenerate foundation docs from tokens
`
$3
- 4-Axis Controls: Color Brand, Content Brand, Theme, Density
- Component Stories: All variants with controls
- Styleguide Pages: Colors, Typography, Spacing, Effects (auto-generated)
- Dark Mode Toggle: Synced with design tokens
$3
Foundation pages (Colors, Typography, Spacing, Effects) are automatically generated from token JSON files by scripts/tokens/generate-docs.js. This ensures documentation stays in sync with the actual token values.
`bash
Regenerate docs after token changes

npm run build:docs
`| Page | Source |
|------|--------|
| Colors | Semantic > Color tokens |
| Typography | Semantic > Typography tokens |
| Spacing | Semantic > Space tokens (Inline, Stack, Gap) |
| Effects | Semantic shadow tokens |
$3
`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
    
      ${args.label}
    
  ,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost'],
    },
  },
};
export default meta;
export const Primary: StoryObj = {
  args: { variant: 'primary', label: 'Click me' },
};
``
---
🔗 Related
| Document | Description |
|----------|-------------|
| 📖 Main README | Project overview |
| 📖 React Wrappers | React wrapper components |
| 📖 Vue Wrappers | Vue 3 wrapper components |
| 📖 Tokens README | Design tokens documentation |
| 📖 Icons README | Icon library documentation |
| 📖 CSS Documentation | CSS Custom Properties & Shadow DOM |
---
📄 License
MIT
---
Built with ❤️ for the BILD Design System
| Feature | Status |
|---------|--------|
| Shadow DOM | ✅ |
| CSS Custom Properties | ✅ |
| 4-Axis Theming | ✅ |
| TypeScript | ✅ |
| Storybook | ✅ |
| React Wrappers | ✅ |
| Vue 3 Wrappers | ✅ |