| name | stencil-atomic-design-system |
| description | Use when building a Stencil.js design system with Atomic Design methodology, design tokens, theming support, and slot-based components. Implements a multi-client architecture with standardized patterns for atoms, molecules, organisms, and templates. |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob"] |
Stencil.js Atomic Design System
Build a scalable, themeable design system using Stencil.js with Atomic Design principles, design tokens, and slot-based composition patterns for multi-client deployments.
Project Structure
design-respec/
├── src/
│ ├── components/
│ │ # Atoms - Basic building blocks
│ │ ├── cor-button/
│ │ │ ├── cor-button.tsx
│ │ │ ├── cor-button.css
│ │ │ ├── cor-button.constants.ts
│ │ │ ├── cor-button.enums.ts
│ │ │ ├── cor-button.stories.ts
│ │ │ ├── readme.md
│ │ │ └── test/
│ │ │ └── cor-button.spec.tsx
│ │ ├── cor-icon/
│ │ ├── cor-typography/
│ │ ├── cor-separator/
│ │ # Molecules - Combined components
│ │ ├── cor-input-field/
│ │ ├── cor-toggle/
│ │ ├── cor-search-bar/
│ │ # Organisms - Complex UI structures
│ │ ├── cor-card/
│ │ ├── cor-navbar/
│ │ ├── cor-form/
│ │ # Templates - Page structures
│ │ ├── cor-page-layout/
│ │ └── cor-grid/
│ ├── assets/
│ │ └── css/
│ │ ├── index.css # Main CSS imports
│ │ ├── base/ # Base HTML styles
│ │ └── utilities/ # Utility classes
│ └── utils/
│ └── theme-utils.ts
├── tokens/
│ ├── core/ # Core design tokens
│ │ ├── color.tokens.json
│ │ ├── font.tokens.json
│ │ ├── space.tokens.json
│ │ ├── radius.tokens.json
│ │ ├── shadow.tokens.json
│ │ ├── border.tokens.json
│ │ ├── components/ # Component-specific tokens
│ │ └── style-dictionary.config.json
│ ├── respec/ # RESPEC-specific tokens
│ │ └── [theme files]
│ ├── [client-name]/ # Client-specific tokens
│ │ └── [theme overrides]
│ └── generated/ # Auto-generated CSS
│ └── *.css
├── stencil.config.ts
└── package.json
1. Atomic Design Implementation
Atoms - Foundational Elements
import { Component, Prop, h, Host } from '@stencil/core';
@Component({
tag: 'cor-button',
styleUrl: 'cor-button.css',
shadow: true,
})
export class CorButton {
@Prop() variant: 'primary' | 'secondary' | 'tertiary' = 'primary';
@Prop() size: 'small' | 'medium' | 'large' = 'medium';
@Prop() disabled: boolean = false;
render() {
return (
<Host
class={{
[`button--${this.variant}`]: true,
[`button--${this.size}`]: true,
'button--disabled': ,
}}
>
);
}
}
:host {
--button-padding-small: var(--spacing-xs) var(--spacing-sm);
--button-padding-medium: var(--spacing-sm) var(--spacing-md);
--button-padding-large: var(--spacing-md) var(--spacing-lg);
display: inline-block;
}
.button {
font-family: var(--font-family-pro-display);
border-radius: var(--radius-md);
transition: 250ms ease;
cursor: pointer;
border: none;
display: inline-flex;
align-items: center;
gap: var(--spacing-xs);
}
:host(.button--small) .button {
padding: var(--button-padding-small);
font-size: var(--font-size-sm);
}
:host(.button--medium) .button {
padding: var(--button-padding-medium);
font-size: var(--font-size-md);
}
:host(.button--large) .button {
padding: (--button-padding-large);
: (--font-size-lg);
}
() {
: (--color-primary-background-default);
: (--color-primary-text-default);
: (--spacing-px) solid (--color-primary-border-default);
}
() {
: (--color-primary-background-hover);
: (--color-primary-border-hover);
}
() {
: (--color-secondary-background-default);
: (--color-secondary-text-default);
: (--spacing-px) solid (--color-secondary-border-default);
}
() {
: ;
: not-allowed;
}
Molecules - Combined Elements
import { Component, Prop, State, Event, EventEmitter, h, Host } from '@stencil/core';
@Component({
tag: 'cor-input-field',
styleUrl: 'cor-input-field.css',
shadow: true,
})
export class CorInputField {
@Prop() label: string;
@Prop() value: string = '';
@Prop() error: string;
@Prop() helperText: string;
@Prop() required: boolean = false;
@Prop() disabled: boolean = false;
@State() focused: boolean = false;
@Event() valueChange: EventEmitter<string>;
private handleInput = (event: Event) => {
value = (event. ).;
..(value);
};
() {
(
);
}
}
Organisms - Complex Structures
import { Component, Prop, h, Host } from '@stencil/core';
@Component({
tag: 'cor-card',
styleUrl: 'cor-card.css',
shadow: true,
})
export class CorCard {
@Prop() elevated: boolean = false;
@Prop() interactive: boolean = false;
render() {
return (
<Host
class={{
'card--elevated': this.elevated,
'card--interactive': this.interactive,
}}
>
<article class="card">
<slot name="header"></slot>
<div class="card__body">
<slot></slot>
);
}
}
Templates - Page Structures
import { Component, Prop, h, Host } from '@stencil/core';
@Component({
tag: 'cor-page-layout',
styleUrl: 'cor-page-layout.css',
shadow: true,
})
export class CorPageLayout {
@Prop() sidebarPosition: 'left' | 'right' = 'left';
@Prop() hasHeader: boolean = true;
@Prop() hasFooter: boolean = false;
render() {
return (
<Host class={`layout--sidebar-${this.sidebarPosition}`}>
<div class="layout">
{this.hasHeader && (
<header class="layout__header">
<slot name="header"></slot>
</header>
)}
{this.hasFooter && (
)}
);
}
}
2. Design Tokens Framework
Three-Tier Token Hierarchy
Tokens are defined in JSON format and processed by Style Dictionary to generate CSS variables.
Core Tokens (Foundation)
{
"color": {
"palette": {
"blue": {
"50": { "value": "#e3f2fd" },
"100": { "value": "#bbdefb" },
"200": { "value": "#90caf9" },
"300": { "value": "#64b5f6" },
"400": { "value": "#42a5f5" },
"500": { "value": "#2196f3" }
{
"font": {
"family": {
"pro-display": {
"value": "SF Pro Display, -apple-system, BlinkMacSystemFont, sans-serif"
},
"pro-text": {
"value": "SF Pro Text, -apple-system, BlinkMacSystemFont, sans-serif"
},
"mono": {
"value": "SF Mono, Monaco, monospace"
}
},
"size": {
"xs": { "value": "0.75rem" },
"sm": { "value": "0.875rem" },
"md": {
{
"space": {
"px": { "value": "1px" },
"2xs": { "value": "0.125rem" },
"xs": { "value": "0.25rem" },
"sm": { "value": "0.5rem" },
"md": { "value": "0.75rem" },
"lg": { "value": "1rem" },
"xl": { "value": "1.5rem"
Component Tokens
{
"button": {
"primary": {
"background": {
"default": { "value": "{color.palette.blue.600}" },
"hover": { "value": "{color.palette.blue.700}" },
"active": { "value": "{color.palette.blue.800}" },
"disabled": { "value": "{color.palette.blue.200}" }
},
"text": {
"default": { "value": "#ffffff" },
"disabled"
Theme Support
:root,
[data-theme="light"] {
--ds-color-background: white;
--ds-color-surface: white;
--ds-color-text-primary: var(--ds-color-gray-900);
--ds-color-text-secondary: var(--ds-color-gray-600);
}
[data-theme="dark"] {
--ds-color-background: var(--ds-color-gray-900);
--ds-color-surface: var(--ds-color-gray-800);
--ds-color-text-primary: white;
--ds-color-text-secondary: var(--ds-color-gray-300);
--ds-border-color: var(--ds-color-gray-700);
}
Global CSS Setup
@import 'base/html.css';
@import 'utilities/scrollbars.css';
@import 'utilities/overlays.css';
Token Processing with Style Dictionary
{
"source": ["tokens/core/**/*.json"],
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "../generated/",
"files": [
{
"destination": "core.css",
"format": "css/variables"
}
]
}
}
}
3. Slot-Based Component Architecture
Why Slots Over Props
Slots provide better flexibility, composability, and performance for content projection:
@Component({ tag: 'ds-button-bad' })
export class BadButton {
@Prop() label: string;
@Prop() iconLeft: string;
@Prop() iconRight: string;
render() {
return (
<button>
{this.iconLeft && <ds-icon name={this.iconLeft} />}
{this.label}
{this.iconRight && <ds-icon name={this.iconRight} />}
</button>
);
}
}
@Component({ tag: 'ds-button' })
export class Button {
render() {
return (
<button>
<slot name="icon-left"></slot>
<slot></slot>
<slot name=>
);
}
}
Slot Patterns
Default and Named Slots
@Component({ tag: 'ds-modal' })
export class Modal {
render() {
return (
<div class="modal">
<div class="modal__header">
<slot name="header"></slot>
</div>
<div class="modal__body">
<slot></slot> {/* Default slot */}
</div>
<div class="modal__footer">
<slot name="footer"></slot>
</div>
</div>
);
}
}
Usage:
<ds-modal>
<h2 slot="header">Modal Title</h2>
<p>This is the body content in the default slot</p>
<div slot="footer">
<ds-button>Cancel</ds-button>
<ds-button variant="primary">Confirm</ds-button>
</div>
</ds-modal>
Conditional Slot Rendering
@Component({ tag: 'ds-alert' })
export class Alert {
@Element() el: HTMLElement;
@State() hasIcon: boolean = false;
componentWillLoad() {
this.hasIcon = !!this.el.querySelector('[slot="icon"]');
}
render() {
return (
<div class={{ 'alert': true, 'alert--has-icon': this.hasIcon }}>
{this.hasIcon && (
<div class="alert__icon">
<slot name="icon"></slot>
</div>
)}
<div class="alert__content">
<slot></slot>
</div>
);
}
}
Slot Fallback Content
@Component({ tag: 'ds-avatar' })
export class Avatar {
@Prop() name: string;
render() {
const initials = this.name
?.split(' ')
.map(word => word[0])
.join('')
.toUpperCase();
return (
<div class="avatar">
<slot>
{/* Fallback content when slot is empty */}
<span class="avatar__initials">{initials}</span>
</slot>
</div>
);
}
}
4. Multi-Client Theming Architecture
Theme Structure
tokens/
├── core/ # Base design tokens
├── respec/ # RESPEC-specific overrides
├── [client-name]/ # Client-specific tokens
└── generated/ # Auto-generated CSS from Style Dictionary
├── core.css
├── respec.css
└── [client-name].css
Build Configuration
import { Config } from '@stencil/core';
import { reactOutputTarget as react } from '@stencil/react-output-target';
import { postcss } from '@stencil/postcss';
import postcssNested from 'postcss-nested';
export const config: Config = {
namespace: 'design-system',
srcDir: 'src',
globalStyle: 'src/assets/css/index.css',
outputTargets: [
{
type: 'dist',
esmLoaderPath: '../loader',
copy: [
{
src: '../tokens/generated/*.css',
dest: 'tokens',
warn: false,
},
],
},
{
type: 'dist-custom-elements',
copy: [
{
src: '**/*.{jpg,png}',
dest: 'dist/components/assets',
warn: true,
},
],
},
{
type: 'docs-readme',
},
{
type: 'www',
: ,
},
({
: ,
}),
],
: [
({
: [()],
}),
],
};
Build Scripts
{
"scripts": {
"build": "npm run tokens:build && stencil build",
"build:react": "npm run tokens:build && stencil build --react",
"start": "stencil build --dev --watch --serve",
"test": "stencil test --spec --e2e",
"test:watch": "stencil test --spec --e2e --watchAll",
"tokens:build": "style-dictionary build --config ./tokens/core/style-dictionary.config.json",
"storybook": "storybook dev -p 6006",
"build-storybook": "storybook build"
}
}
5. Component File Structure
Each component follows this structure:
src/components/cor-[component-name]/
├── cor-[component-name].tsx # Component implementation
├── cor-[component-name].css # Component styles
├── cor-[component-name].enums.ts # Enums for props
├── cor-[component-name].constants.ts # Constants
├── cor-[component-name].stories.ts # Storybook stories
├── readme.md # Auto-generated docs
└── test/
├── cor-[component-name].spec.tsx # Unit tests
└── cor-[component-name].e2e.ts # E2E tests
6. CSS Variable Naming Convention
The project uses flat CSS variable naming without prefixes:
--color-primary-background-default
--color-primary-background-hover
--font-family-pro-display
--font-size-md
--spacing-lg
--radius-md
--shadow-sm
--line-height-base
--font-weight-semi-bold
7. Best Practices
Component Development
- Use cor- prefix for all components
- Slot-based composition over props for content
- Enums for prop values in separate .enums.ts files
- Constants in separate .constants.ts files
- TypeScript strict mode for type safety
- CSS variables for all design tokens
- PostCSS with nested syntax for styles
Token Management
- JSON format for token definitions
- Style Dictionary for token processing
- Three-tier hierarchy: Core → Theme → Component
- Reference tokens using
{token.path} syntax
- Auto-generate CSS from JSON tokens
Testing
- Unit tests with
@stencil/core/testing
- E2E tests for user interactions
- Storybook stories for visual testing
- Test file naming:
*.spec.tsx for unit, *.e2e.ts for E2E
Documentation
- JSDoc comments for public APIs
- Auto-generated readme from component metadata
- Storybook for interactive documentation
- Component stories showing all variations
