| Other Libs | The PDS Way |
|-------------|-------------|
| class="flex items-center gap-4 p-6 bg-white rounded-lg shadow-md" | class="card" |
| style="color: #007acc;" | Uses --color-primary-500 token |
| Import a component | |
| 47 utility classes per element | Semantic class + maybe one layout utility |

The result: Readable HTML. Inspectable CSS. Sites that work without JS. Code that lasts decades.

PDS follows the Pure Web Manifesto—sustainable architecture for long-lived applications.

---

Key Features

- 🎨 Configuration-Driven — Single source of truth generates everything
- 🚀 Live or Static — Runtime generation or pre-built CSS
- 🎯 Framework Agnostic — Vanilla, Lit, React, Vue, Svelte, Next.js
- 🌐 Web Standards — HTMLElement API, Constructable Stylesheets, Shadow DOM, etc.
- 🧩 Progressive Enhancement — Semantic HTML first, enhance where needed
- ♿ Accessibility Built-in — WCAG AA validation, contrast checking
- 📦 Zero Build Required — Works directly in browsers
- 📋 IDE IntelliSense — Full autocomplete via Custom Elements Manifest

---

Table of Contents

- The Three Layers
- Who is it For?
- Getting Started
- Core Architecture
- Styling Layers
- Shadow DOM Adoption
- Icon System
- Smart Query System
- Design Validation
- Advanced Features
- API Reference
- Extending PDS
- Using from CDN
- CLI & Export
- Custom Elements Manifest
- Framework Integration
- Troubleshooting
- License

---

The Four Layers

PDS is built on three fully optional layers, each powered by your config, and a great DX layer on top:

$3

Your config generates:
- Color scales (50–900 from base colors)
- Surface semantics (bg, text, border, shadow, states)
- Spacing system (mathematical progression)
- Typography scale (modular scale from base)
- Primitives (.btn-primary, .card, .badge)
- Utilities (.flex, .gap-md, .stack-lg)

All exported as CSS Custom Properties. Zero specificity via :where().
Same values available in JS via PDS.compiled.tokens.

$3

Optional selector-based upgrades that run in Light DOM and Shadow DOM:
- Required fields show markers and help text automatically
- becomes a switch
-

Menu


`html


Features:
- Click to toggle visibility
- Auto-positioning (up/down based on space)
- Horizontal alignment (.align-right class)
- Keyboard support (Escape to close)
- Click-outside to close
- Scrollable when content exceeds viewport
- Panel can be any last child element (menu, card, form, etc.)

Toggle Switches -

`html

Enable notifications


`

Creates styled toggle switches from standard checkboxes.

Range Sliders -

`html


Volume





Volume


`

Enhances range inputs with automatic value display. Use range-output class for inline output with semantic

element.

Required Field Indicators - form [required]

`html

Email


`

Automatically adds asterisk to label.

#### Custom Enhancers

Add your own progressive enhancements:

`javascript
await PDS.start({
enhancers: [
{
selector: '[data-tooltip]',
description: 'Adds tooltip on hover',
run: (element) => {
const text = element.dataset.tooltip;
element.addEventListener('mouseenter', () => {
// Show tooltip
});
}
},
{
selector: '[data-copy]',
description: 'Copy text to clipboard on click',
run: (element) => {
element.addEventListener('click', () => {
navigator.clipboard.writeText(element.dataset.copy);
});
}
}
]
});
`

$3

Rich, reusable UI components built with Lit. Lazy-loaded automatically via the Auto-Define system.

#### Available Components

- SVG sprite icons
`html




`

Attributes:
- icon - Symbol ID (required)
- size - Named size (xs/sm/md/lg/xl/2xl) or pixel value
- color - CSS color (defaults to currentColor)
- label - Accessible name (makes icon role="img")

- Slide-out panels
`html



Menu


Open Menu

`

Attributes:
- position - left/right/top/bottom
- open - Boolean, controls visibility

Methods:
- open() - Show drawer
- close() - Hide drawer
- toggle() - Toggle visibility

- Accessible tab interface
`html

Overview


- File upload with preview
`html
accept="image/*"
multiple
max-size="5000000">

`

Attributes:
- accept - File types (MIME or extensions)
- multiple - Allow multiple files
- max-size - Max file size in bytes
- max-files - Max number of files

Events:
- files-changed - Fired when selection changes
- file-error - Fired on validation errors

- Toast notifications
`html



`

Or use via events:
`javascript
PDS.dispatchEvent(new CustomEvent('pds:toast', {
detail: {
message: 'Error occurred',
type: 'danger',
duration: 5000
}
}));
`

- Rich text editor
`html


value="

Initial content

Set format="markdown" when you want the submitted form value to stay in Markdown:
`html

`
The element will use the #showdown import-map specifier first, and will only fall back to loading the script from CDNs if that specifier is missing.

Features:
- Bold, italic, underline, strikethrough
- Headings, lists, links
- Code blocks
- Undo/redo
- Markdown shortcuts

- Dynamic forms from JSON Schema
`html

`

Generates complete forms with validation from JSON Schema.

- Resizable panes
`html



- Horizontal scrolling container
`html



`javascript
await PDS.start({
autoDefine: {
baseURL: '/auto-define/',

// Eagerly load these components
predefine: ['pds-icon', 'pds-drawer'],

// Custom file mapping
mapper: (tag) => {
if (tag.startsWith('my-')) {
return /components/${tag}.js;
}
// Return nothing to use PDS default mapping
},

// Advanced options
scanExisting: true, // Scan for tags on init
observeShadows: true, // Watch Shadow DOM
patchAttachShadow: true, // Monitor dynamic shadows
debounceMs: 16 // Debounce observation
}
});
`

The system:
1. Observes DOM for new custom elements
2. Checks if tag is defined
3. Loads corresponding module
4. Registers custom element
5. Upgrades existing instances

> ⚠️ Important: Programmatic Access to Auto-Defined Components
>
> Components loaded via autoDefine are registered asynchronously. If you need to access component methods or properties programmatically (e.g., toaster.toast()), ensure the component is defined first:
>
> `javascript
> // Wait for component to be defined
> await customElements.whenDefined('pds-toaster');
> const toaster = document.querySelector('pds-toaster');
> toaster.toast('Hello!');
> `
>
> Alternative: Use predefine to eagerly load components at PDS.start() time:
>
> `javascript
> await PDS.start({
> autoDefine: {
> predefine: ['pds-toaster', 'pds-icon'] // Loaded immediately
> }
> });
> // Components are now available synchronously
> `

---

Styling Layers

PDS generates CSS in structured layers for predictable specificity and modularity.

$3

`
┌──────────────────────────────────────────────────────────┐
│ tokens CSS Custom Properties │
│ --color-, --spacing-, --font-* │
├──────────────────────────────────────────────────────────┤
│ primitives Base elements │
│ button, input, .card, .badge │
├──────────────────────────────────────────────────────────┤
│ components Rich UI │
│ .drawer, .tabstrip, .upload │
├──────────────────────────────────────────────────────────┤
│ utilities Composable helpers │
│ .flex, .gap-4, .border-gradient │
└──────────────────────────────────────────────────────────┘
`

$3

Tokens - Design foundation
- Colors (scales + semantics)
- Spacing (0-12 progression)
- Typography (families, sizes, weights)
- Borders (widths, radius)
- Shadows (depths)
- Transitions (speeds)
- Z-index (layers)
- Layout (breakpoints, max-width)

Primitives - Native elements enhanced
- Buttons (.btn-primary, .btn-secondary, .btn-outline)
- Forms (input, select, textarea, fieldset)
- Surfaces (.card, .surface)
- Badges (.badge, .badge-success)
- Callouts (.callout, .callout-warning)
- Typography (headings, paragraphs, lists)
- Tables (responsive, striped)

Components - Web Component styles
- Styles for elements
- Internal component structure
- State management (:state() selectors)

Utilities - Layout and effects
- Flex (.flex, .flex-col, .items-center)
- Grid (.grid, .grid-cols-3)
- Spacing (.gap-4, .p-4, .m-2)
- Borders (.border, .border-gradient, .border-glow)
- Effects (.shadow-lg, .rounded-lg)

$3

In live mode:
`javascript
const compiled = PDS.compiled;

// Get layer CSS
const tokensCSS = compiled.layers.tokens.css;
const primitivesCSS = compiled.layers.primitives.css;

// Get as stylesheet
const sheet = await PDS.registry.getStylesheet('primitives');
`

In static mode:
`javascript
// Import constructable stylesheets
import tokensSheet from '/pds/styles/pds-tokens.css.js';
import primitivesSheet from '/pds/styles/pds-primitives.css.js';
`

---

Shadow DOM Adoption

PDS provides helpers for adopting styles into Shadow DOM.

$3

`javascript
class MyComponent extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
}

async connectedCallback() {
// Adopt just primitives (most common)
await PDS.adoptPrimitives(this.shadowRoot);

this.shadowRoot.innerHTML =
Click me
;
}
}
`

$3

`javascript
// Adopt specific layers
await PDS.adoptLayers(this.shadowRoot, ['primitives', 'components']);

// Adopt with custom styles
const myStyles = PDS.createStylesheet(
:host {
display: block;
padding: var(--spacing-4);
}
);

await PDS.adoptLayers(this.shadowRoot, ['primitives'], [myStyles]);
`

$3

`javascript
import { html, css, LitElement } from '#pds/lit';

class MyCard extends LitElement {
static styles = css
:host {
display: block;
}
;

async connectedCallback() {
super.connectedCallback();
await PDS.adoptPrimitives(this.shadowRoot);
}

render() {
return html

`html





`

$3

`javascript
await PDS.start({
design: {
icons: {
set: 'phosphor', // Icon family
weight: 'regular', // Icon weight
defaultSize: 24, // Default size in pixels
sizes: { // Named sizes
xs: 16,
sm: 20,
md: 24,
lg: 32,
xl: 48,
'2xl': 64
},
spritePath: '/assets/pds/icons/pds-icons.svg'
}
}
});
`

$3

Add custom icons to the sprite:

1. Configure custom icons:
`javascript
// pds.config.js
export default {
design: {
icons: {
set: 'phosphor',
include: [
'house', 'gear', 'heart', 'star',
'user', 'bell', 'search', 'menu'
]
}
}
};
`

2. Rebuild sprite:
`bash
npm run pds:build-icons
`

3. Use in your app:
`html

`

$3

Icons are available as CSS custom properties:

`css
--icon-set: phosphor;
--icon-weight: regular;
--icon-size-xs: 16px;
--icon-size-sm: 20px;
--icon-size-md: 24px;
--icon-size-lg: 32px;
`

---

Smart Query System

Ask questions about your design system using natural language.

$3

`javascript
// Programmatic API
const results = await PDS.query("what is the focus border color on inputs?");

results.forEach(result => {
console.log(result.text); // "Focus border color: var(--color-primary-500)"
console.log(result.category); // "Color Token"
console.log(result.cssVar); // "var(--color-primary-500)"
console.log(result.code); // Example code
});
`

$3

Color Questions:
`javascript
await PDS.query("what is the focus border color on inputs?")
await PDS.query("what foreground color should I use on this surface?")
await PDS.query("button hover color")
await PDS.query("primary color scale")
`

Utility Questions:
`javascript
await PDS.query("what are the utility classes for borders?")
await PDS.query("border gradient effect")
await PDS.query("flex layout utilities")
await PDS.query("gap between elements")
`

Component Questions:
`javascript
await PDS.query("how do I create an icon-only button?")
await PDS.query("drawer component")
await PDS.query("tab strip usage")
`

Layout Questions:
`javascript
await PDS.query("how can I group stuff in containers?")
await PDS.query("grid container")
await PDS.query("card component")
`

$3

The query system integrates with #pds-search in the configurator. Type queries directly in the search box for instant answers.

$3

1. Intent Detection - Recognizes what you're asking about (color, spacing, component, utility)
2. Entity Recognition - Identifies design elements (button, input, surface)
3. Context Analysis - Detects states (hover, focus, active)
4. Data Querying - Searches PDS.compiled, PDS.ontology, PDS.currentConfig
5. Scoring & Ranking - Returns top 10 most relevant results

See PDS-QUERY-SYSTEM.md for detailed documentation.

---

Design Validation

PDS automatically validates designs for accessibility issues.

$3

In live mode with presets enabled:

`bash
npm run build
`

Validates all presets during build and reports issues:

`
❌ Preset validation failed:

— Travel Market
• Primary text on surface is too low (3.95 < 4.5)
[light/outline] (/colors/primary)

— Mobility App
• Primary button contrast too low in dark theme (2.85 < 4.5)
[dark/btn-primary] (/colors/darkMode/primary)
`

$3

`javascript
import { validateDesign } from '@pure-ds/core/pds-core/pds-generator.js';

const result = validateDesign({
colors: {
primary: '#007acc',
background: '#ffffff'
}
}, {
minContrast: 4.5 // WCAG AA standard
});

if (!result.ok) {
console.table(result.issues);
// [
// {
// path: '/colors/primary',
// message: 'Primary button contrast too low...',
// ratio: 3.2,
// min: 4.5,
// context: 'light/btn-primary'
// }
// ]
}
`

$3

`javascript
import { validateDesigns } from '@pure-ds/core/pds-core/pds-generator.js';

const results = validateDesigns([
{ name: 'Light', config: {...} },
{ name: 'Dark', config: {...} }
], {
minContrast: 4.5
});

results.forEach(({ name, ok, issues }) => {
if (!ok) {
console.log(${name} has ${issues.length} issues);
}
});
`

$3

- Primary Button (Light) - Button fill vs white text
- Primary Button (Dark) - Button fill vs white text in dark mode
- Surface Text (Light) - Text color vs surface background
- Primary Links/Outline (Light) - Primary text vs surface
- Surface Text (Dark) - Text color vs dark surface

All checks verify WCAG AA minimum contrast ratio (4.5:1 default).

---

Advanced Features

$3

In live mode, PDS automatically loads fonts from Google Fonts when they're not available locally.

`javascript
await PDS.start({
mode: 'live',
design: {
typography: {
fontFamilyHeadings: 'Inter, sans-serif',
fontFamilyBody: 'Inter, sans-serif',
fontFamilyMono: 'Fira Code, monospace'
}
}
});

// Fonts are automatically loaded from Google Fonts if needed
`

Features:
- Smart detection (skips system fonts)
- Parallel loading for performance
- Font weights: 400, 500, 600, 700
- font-display: swap for better UX
- 5-second timeout prevents hanging

Manual loading:
`javascript
import { loadGoogleFont } from '@pure-ds/core/common/font-loader';

await loadGoogleFont('Roboto', {
weights: [400, 500, 700],
italic: true
});
`

$3

PDS is an EventTarget - listen for system events:

`javascript
// System ready
PDS.addEventListener('pds:ready', (e) => {
console.log('PDS ready:', e.detail.mode);
});

// Theme changed
PDS.addEventListener('pds:theme:changed', (e) => {
console.log('Theme:', e.detail.theme);
});

// Design updated (configurator)
PDS.addEventListener('pds:design:updated', (e) => {
console.log('New config:', e.detail.config);
});

// Error handling
PDS.addEventListener('pds:error', (e) => {
console.error('PDS error:', e.detail.error);
});
`

Available events:
- pds:ready - System initialized
- pds:error - Error occurred
- pds:theme:changed - Theme switched
- pds:design:updated - Config changed
- pds:design:field:changed - Single field updated
- pds:inspector:mode:changed - Inspector toggled
- pds:inspector:deactivate - Inspector close requested
- pds:docs:view - Documentation view requested
- pds:toast - Toast notification triggered

$3

`javascript
// Get current theme
const theme = PDS.theme; // 'light' | 'dark' | 'system' | null

// Set theme
PDS.theme = 'dark';
PDS.theme = 'system'; // Follows OS preference
PDS.theme = null; // Remove preference
`

Theme is stored in localStorage and updates html[data-theme] automatically.

$3

In live mode, access the complete generated system:

`javascript
const compiled = PDS.compiled;

// Tokens
compiled.tokens.colors.primary[500];
compiled.tokens.spacing[4];
compiled.tokens.typography.fontFamily.body;

// Layers
compiled.layers.tokens.css;
compiled.layers.primitives.css;

// Metadata
compiled.meta.generatedAt;
compiled.meta.totalSize;
compiled.meta.tokenGroups;

// Helpers
compiled.helpers.getColorScales();
compiled.helpers.getColorScale('primary');
compiled.helpers.getSpacingValues();
`

$3

Choose from built-in presets:

`javascript
// View available presets
Object.keys(PDS.presets);
// ['default', 'ocean-breeze', 'midnight-steel', ...]

// Use a preset
await PDS.start({
preset: 'ocean-breeze',
design: {
// Override specific values
colors: { primary: '#custom' }
}
});

// Access preset config
const preset = PDS.presets['ocean-breeze'];
console.log(preset.colors.primary);
`

Available presets:
- default - Clean, modern baseline
- ocean-breeze - Cool blues and teals
- midnight-steel - Dark, professional
- sunset-vibes - Warm oranges and purples
- forest-calm - Natural greens
- lavender-dream - Soft purples
- coral-energy - Vibrant pinks and oranges
- arctic-frost - Cool grays and blues
- golden-hour - Warm yellows and golds
- neon-city - Bright, high-contrast
- travel-market - Earthy, adventurous
- mobility-app - Tech-forward transportation

---

API Reference

$3

Main initialization method.

`typescript
await PDS.start({
// Mode
mode?: 'live' | 'static' = 'live',

// Design configuration
preset?: string,
design?: {
colors?: {...},
typography?: {...},
spatialRhythm?: {...},
shape?: {...},
behavior?: {...},
layout?: {...},
layers?: {...},
icons?: {...}
},

// Static mode paths
staticPaths?: {
tokens?: string,
primitives?: string,
components?: string,
utilities?: string,
styles?: string
},

// Component loading
autoDefine?: {
baseURL?: string,
predefine?: string[],
mapper?: (tag: string) => string | void,
scanExisting?: boolean,
observeShadows?: boolean,
patchAttachShadow?: boolean,
debounceMs?: number
},

// Progressive enhancements
enhancers?: Array<{
selector: string,
description?: string,
run: (element: Element) => void
}>,

// Runtime options
applyGlobalStyles?: boolean = false,
manageTheme?: boolean = false,
themeStorageKey?: string = 'pure-ds-theme',
preloadStyles?: boolean = false,
criticalLayers?: string[] = ['tokens', 'primitives']
});
`

$3

Smart query interface.

`typescript
const results = await PDS.query(question: string);
// Returns array of results with text, value, icon, category, etc.
`

$3

Validate design for accessibility.

`typescript
import { validateDesign } from '@pure-ds/core/pds-core/pds-generator.js';

const result = validateDesign(config, { minContrast: 4.5 });
// Returns: { ok: boolean, issues: Array }
`

$3

Adopt stylesheets into Shadow DOM.

`typescript
await PDS.adoptLayers(shadowRoot, ['primitives'], [customSheet]);
`

$3

Adopt primitives layer (convenience method).

$3

Create constructable stylesheet from CSS string.

$3

`typescript
PDS.registry // Runtime registry
PDS.getGenerator() // Live-only Generator accessor
PDS.ontology // Design system metadata (live-only)
PDS.presets // Built-in presets (live-only)
PDS.enums // Enumeration values (live-only)
PDS.currentConfig // Current configuration (read-only)
PDS.compiled // Compiled state (live mode only)
PDS.theme // Current theme (getter/setter)
PDS.defaultEnhancers // Built-in enhancements
`

---

Extending PDS

$3

`javascript
await PDS.start({
enhancers: [
{
selector: '[data-animate-in]',
description: 'Animate elements as they enter viewport',
run: (element) => {
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
element.classList.add('animated');
observer.unobserve(element);
}
});
});
observer.observe(element);
}
}
]
});
`

$3

`javascript
await PDS.start({
autoDefine: {
mapper: (tag) => {
if (tag.startsWith('my-')) {
return /components/${tag}.js;
}
// Let PDS handle pds-* components
}
}
});
`

$3

`javascript
export const myPreset = {
id: 'my-brand',
name: 'My Brand Theme',
colors: { primary: '#007acc', secondary: '#5c2d91' },
typography: { fontFamilyHeadings: 'Montserrat' }
};

await PDS.start({ design: myPreset });
`

---

Using from CDN

`html






Click me




`

---

CLI & Build

$3

| Script | Description |
|--------|-------------|
| npm run pds:build | Full build: styles, components, icons, and IntelliSense data |
| npm run pds:dx | Generate all IntelliSense data (HTML + CSS) |
| npm run pds:manifest | Generate HTML IntelliSense (Custom Elements Manifest) |
| npm run pds:css-data | Generate CSS IntelliSense (tokens, classes, attributes) |
| npm run pds:build-icons | Build custom icon sprite |
| npm run sync-assets | Sync assets between locations |
| npx pds-init-config | Create default pds.config.js with helpful examples |

$3

Create a starter pds.config.js file with commented examples:

`bash


Create config in current directory

This generates a pds.config.js with:
- Basic mode and preset settings
- Commented examples for design token overrides
- Template for custom progressive enhancers
- Template for lazy-loaded component configuration

Note: During npm install, PDS automatically creates this file if it doesn't exist.

$3

`bash
npm run pds:build
`

Output:
`
pds/
├── styles/
│ ├── pds-tokens.css
│ ├── pds-tokens.css.js
│ ├── pds-primitives.css
│ ├── pds-primitives.css.js
│ ├── pds-components.css
│ ├── pds-components.css.js
│ ├── pds-utilities.css
│ ├── pds-utilities.css.js
│ └── pds-styles.css.js
├── components/
│ └── pds-*.js (all components)
├── icons/
│ └── pds-icons.svg
├── custom-elements.json # HTML IntelliSense
├── vscode-custom-data.json # HTML IntelliSense (VS Code)
├── pds.css-data.json # CSS IntelliSense (VS Code)
└── pds-css-complete.json # CSS IntelliSense (all editors)
`

$3

For complete IDE support with autocomplete:

`bash


Generate both HTML and CSS IntelliSense (recommended)

`javascript
// pds.config.js
export default {
staticBase: 'pds',
static: { root: 'public/assets/pds/' },
preset: 'default',
design: { colors: { primary: '#007acc' } }
};
`

$3

`bash
npm run pds:build-icons
`

$3

`bash
npm run sync-assets
`

---

IntelliSense & IDE Support

PDS provides comprehensive IntelliSense support for both HTML and CSS, dramatically improving developer experience with autocomplete, documentation, and type hints.

> 📖 Full IntelliSense Guide - Detailed setup for all editors

$3

Add to .vscode/settings.json:

`json
{
"html.customData": [
"node_modules/@pure-ds/core/public/assets/pds/vscode-custom-data.json"
],
"css.customData": [
"node_modules/@pure-ds/core/public/assets/pds/pds.css-data.json"
]
}
`

Reload VS Code: Ctrl+Shift+P → Developer: Reload Window

$3

#### HTML IntelliSense
- ✅ Web component autocomplete (, )
- ✅ Attribute suggestions with descriptions
- ✅ Enum value autocomplete (position="left|right|top|bottom")
- ✅ Icon name suggestions (all available icons)

#### CSS IntelliSense
- ✅ CSS token autocomplete in .css files and