BILD Design System Web Components - Stencil-based component library
npm install @marioschmidt/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.


---
- š¦ Installation
- š Usage
- āļø React & Vue
- š§© Available Components
- šØ Theming
- š Shadow DOM
- š Project Structure
- āļø Development
- š Storybook
- š Related
- š License
---
``bash`
npm install @marioschmidt/design-system-components
Recommended: Install together with design tokens:
`bash`
npm install @marioschmidt/design-system-tokens @marioschmidt/design-system-components
---
`javascript
import { defineCustomElements } from '@marioschmidt/design-system-components/loader';
// Register all components (lazy-loaded on first use)
defineCustomElements();
`
`javascript`
// Import and auto-register all components
import '@marioschmidt/design-system-components/components';
`javascript`
import { DsButton, DsCard } from '@marioschmidt/design-system-components';
`html
Card content goes here.
Card Title
`
---
For better framework integration, use our auto-generated wrapper packages:
`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 (
$3
`bash
npm install @marioschmidt/design-system-vue
``vue
Click me
`---
š§© 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 3333Build components
npm run build:componentsBuild everything (tokens + icons + components)
npm run build:allClean 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
,
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary', 'ghost'],
},
},
};export default meta;
export const Primary: StoryObj = {
args: { variant: 'primary', label: 'Click me' },
};
``---
| 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 |
---
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 | ā
|