Shows scroll buttons when content overflows.
#### Auto-Define System
Components are registered automatically when their tags appear in the DOM:
`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---
Styling Layers PDS generates CSS in structured layers for predictable specificity and modularity.
$3
`
$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) - 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 Card Title Card content
Action ; } }`---
Icon System PDS uses SVG sprites for efficient icon rendering.
$3
`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 resultsSee 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 hangingManual 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:
`bashCreate config in current directory npx pds-init-config
Force overwrite existing config npx pds-init-config --force`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 configurationNote: 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:
`bashGenerate both HTML and CSS IntelliSense (recommended) npm run pds:dx
Or generate individually npm run pds:manifest # HTML component autocomplete npm run pds:css-data # CSS token & class autocomplete`See INTELLISENSE.md for setup instructions.
$3
`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