{ "$schema": "dss-core-v1", "version": "1.3.0", "last_updated": "2025-12-10", "purpose": "Single source of truth for AI agents working with DSS", "meta": { "schema_ref": "https://sofi.internal/dss/schemas/dss-core-v1.json", "compat": { "min_admin_ui": "0.6.0", "min_cli": "0.4.0", "min_mcp_server": "0.3.0" }, "status": "stable", "owners": ["dss-core@sofi.com"], "tags": ["design-system", "tokens", "figma", "storybook", "mcp"] }, "what_is_dss": { "description": "Design System Server - monolithic platform for design token management", "core_function": "Ingest tokens from multiple sources, normalize to canonical format, generate outputs", "philosophy": "DSS structure is sacred - external systems adapt TO DSS, not reverse" }, "core_principles": { "no_deployment": { "rule": "DSS runs ONLY in development mode - there is no production deployment", "environment": "Single development instance serves all purposes", "url": "dss.overbits.luz.uy points to dev server, NOT a production build", "implication": "Always use 'npm run dev', never deploy dist/ to production" }, "single_source_of_truth": "All design tokens flow through DSS canonical structure", "figma_authority": "Figma is the source of truth for design decisions" }, "canonical_structure": { "tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"], "components": "59 shadcn/ui components - see .dss/components/shadcn-registry.json", "patterns": ["forms", "navigation", "layouts"], "rule": "This structure NEVER changes. All inputs normalize to this." }, "key_concepts": { "translation_dictionaries": { "what": "Per-project mappings from external systems to DSS canonical tokens", "flow": "Source tokens -> Translation layer -> DSS canonical -> Output" }, "custom_props": { "what": "Client-specific properties outside DSS core", "namespace": "color.brand.{client}.*", "rule": "Never modify DSS core - add to custom namespace" }, "merge_strategies": { "FIRST": "Keep first occurrence", "LAST": "Override with latest", "PREFER_FIGMA": "Prioritize Figma source", "PREFER_CODE": "Prioritize CSS/SCSS", "PREFER_SPECIFIC": "Prefer concrete values over references", "MERGE_METADATA": "Combine metadata, use latest value" } }, "architecture": { "layers": { "router": "MCP Server (36 tools), REST API (34 endpoints), CLI", "messaging": "Circuit breaker, Activity log, Event emitter", "workflows": "Figma client, Token ingestion, Storybook generator, Analysis engine, Context compiler, Storage (JSON files)" }, "ports": { "rest_api": 3456, "mcp_server": 3457 }, "dependencies": { "python": ">=3.10", "node": ">=18", "services": ["figma-api", "storybook"] }, "storage": { "type": "JSON files", "location": ".dss/data/", "structure": { "_system": "config, cache, activity logs", "projects/{id}": "manifest, tokens/, components/, styles/, figma/, metrics/", "teams/{id}": "manifest, members, access" }, "philosophy": "Eat our own food - storage mirrors DSS canonical structure" } }, "mcp_tools_categories": { "project_management": ["dss_analyze_project"], "token_ingestion": ["dss_extract_tokens", "dss_transform_tokens", "dss_resolve_token"], "utilities": ["dss_generate_theme", "dss_list_themes", "dss_get_status", "dss_find_quick_wins", "dss_validate_manifest", "dss_list_skins"], "analysis": ["dss_audit_components", "browser_accessibility_audit"], "storybook": ["dss_setup_storybook"], "figma_integration": ["dss_sync_figma"], "browser_tools": ["devtools_launch", "devtools_connect", "devtools_console_logs", "devtools_screenshot", "..."], "context_compiler": ["dss_get_resolved_context", "dss_get_compiler_status"] }, "token_architecture": { "description": "3-Layer Token Cascade with Skin Contract validation", "layers": { "1_core_primitives": { "path": ".dss/core/primitives.json", "purpose": "Raw Tailwind-style values (colors, spacing, radius, fonts)", "immutable": true, "shared": "Across all skins" }, "2_skin": { "path": ".dss/skins/{skin_name}/tokens.json", "purpose": "Semantic mapping from primitives to design tokens", "contract": ".dss/schema/skin-contract.json", "examples": ["shadcn", "heroui", "material"], "rule": "Must provide ALL tokens defined in skin-contract" }, "3_theme": { "path": ".dss/themes/{theme_name}.json", "purpose": "Brand overrides on top of skin", "rule": "May ONLY override tokens defined in skin-contract", "survives": "Skin updates (stable API through contract)" } }, "cascade_flow": "Core Primitives -> Skin (semantic) -> Theme (brand) = Final Tokens", "validation": { "script": "scripts/validate-theme.py", "checks": [ "Skin provides all contract-required tokens", "Theme only overrides contract tokens" ] }, "resolution": { "script": "scripts/resolve-tokens.py", "output": ".dss/data/_system/tokens/tokens.json", "resolves": "Token references like {color.zinc.500} using primitives" }, "storybook_generation": { "script": "scripts/generate-storybook.py", "output": "admin-ui/src/stories/", "generates": [ "Overview.stories.js - Introduction and architecture", "ColorPrimitives.stories.js - Tailwind color palette", "Spacing.stories.js - Spacing scale", "Radius.stories.js - Border radius tokens", "Typography.stories.js - Typography styles from Figma", "Effects.stories.js - Shadows and focus rings", "SemanticColors.stories.js - Semantic color tokens from skin" ] } }, "context_compiler": { "cascade": "Base Skin -> Extended Skin -> Project Overrides = Final Context", "caching": "mtime-based invalidation", "security": "Path traversal prevention, input validation", "lifecycle": { "states": ["idle", "building", "ready", "stale", "error"], "transitions": { "idle->building": "trigger build", "building->ready": "build success", "ready->stale": "source mtime changed", "any->error": "uncaught exception" } } }, "file_paths": { "mcp_server": "dss-claude-plugin/servers/dss-mcp-server.py", "rest_api": "tools/api/server.py", "token_parsers": "tools/ingest/", "analysis": "tools/analyze/", "storage": "tools/storage/json_store.py", "data": ".dss/data/", "schemas": ".dss/schema/", "admin_ui": "admin-ui/", "skills": "dss-claude-plugin/skills/", "commands": "dss-claude-plugin/commands/", "logs": ".dss/logs/", "cache": ".dss/cache/", "core_primitives": ".dss/core/primitives.json", "skin_contract": ".dss/schema/skin-contract.json", "skins": ".dss/skins/", "themes": ".dss/themes/", "token_resolver": "scripts/resolve-tokens.py", "theme_validator": "scripts/validate-theme.py", "storybook_generator": "scripts/generate-storybook.py", "storybook_stories": "admin-ui/src/stories/", "component_registry": ".dss/components/shadcn-registry.json" }, "coding_rules_summary": { "web_components": "Shadow DOM required, lifecycle management, data-action event delegation", "styles": "No inline styles, use CSS custom properties", "events": "No inline handlers, use data-action pattern", "accessibility": "WCAG 2.1 AA, semantic HTML, ARIA attributes", "state": "Context store for global, component state for local, no direct DOM manipulation", "errors": "Use logger utility, structured error codes (E1xxx-E5xxx, S1xxx)", "browser_automation": "MUST use LocalBrowserStrategy from dss-claude-plugin/strategies/local/browser.py - NEVER create ad-hoc Playwright scripts" }, "mandatory_utilities": { "browser_testing": { "class": "LocalBrowserStrategy", "path": "dss-claude-plugin/strategies/local/browser.py", "capabilities": ["console_log_capture", "screenshot", "dom_snapshot", "accessibility_audit", "core_web_vitals"], "rule": "ALWAYS use this class for any browser automation. Never create temporary Playwright scripts." }, "logging": { "module": "dss-claude-plugin/core/structured_logger.py", "rule": "Use structured logging, never print() or console.log for debugging" } }, "error_codes": { "E1xxx": "User errors", "E2xxx": "Validation errors", "E3xxx": "API errors", "E4xxx": "System errors", "E5xxx": "Integration errors", "S1xxx": "Success codes" }, "supported_sources": { "tokens": ["Figma", "CSS", "SCSS", "Tailwind", "JSON"], "output_formats": ["CSS", "SCSS", "JSON", "JS", "Storybook theme"] }, "capabilities": { "ingestion": ["figma", "css", "scss", "tailwind", "json"], "normalization": ["resolve references", "merge metadata", "de-duplicate"], "generation": ["css vars", "scss maps", "json manifests", "storybook themes"], "analysis": ["component audit", "accessibility audit", "quick wins"], "integration": ["mcp tools", "rest api", "cli", "admin-ui"], "governance": ["translation dictionaries", "custom namespaces", "merge strategies"] }, "interfaces": { "rest": { "base": "/api/v1", "endpoints": [ {"path": "/tokens/ingest", "method": "POST", "desc": "Ingest tokens"}, {"path": "/tokens/export", "method": "GET", "desc": "Export normalized tokens"}, {"path": "/context", "method": "GET", "desc": "Resolved context"}, {"path": "/themes", "method": "GET", "desc": "List available themes"} ] }, "cli": { "commands": ["dss ingest", "dss generate", "dss analyze", "dss context"] }, "events": { "emitted": ["ingestion.completed", "context.ready", "theme.generated", "audit.completed"], "subscribed": ["figma.sync", "repo.changed", "cache.invalidate"] } }, "metrics": { "ingestion_time_ms": {"p50": 500, "p95": 2000}, "context_build_ms": {"p50": 800, "p95": 2500}, "cache_hit_rate": {"target": 0.8}, "error_rate": {"target": 0.01} }, "security": { "input_validation": true, "path_sanitization": true, "allowed_sources": ["figma", "filesystem", "repo"], "secrets": { "env": ["FIGMA_TOKEN", "STORYBOOK_TOKEN"], "store": "keychain (macOS) or env" } }, "governance": { "change_control": "PR required for canonical changes", "reviewers": ["design-systems", "frontend-arch"], "versioning": { "core": "semver", "tokens": "schema-tagged versions", "skins": "named releases" } }, "validation": { "schema_checks": ["tokens.json schema", "theme.json schema"], "lint": ["naming conventions", "namespace rules"], "tests": ["ingestion", "merge", "context"] }, "operational": { "logging": { "level": "info", "path": ".dss/logs/dss.log" }, "performance": { "max_workers": 4, "debounce_ms": 250 }, "storage": { "data": ".dss/data/", "cache": ".dss/data/_system/cache/" } }, "examples": { "custom_namespace": "color.brand.acme.primary", "merge_strategy": "PREFER_FIGMA", "cli": "dss ingest --source figma --file tokens.json" }, "component_registry": { "path": ".dss/components/shadcn-registry.json", "source": "shadcn/ui (https://ui.shadcn.com)", "total_components": 59, "categories": { "form": "21 components (Button, Input, Select, Checkbox, etc.)", "data-display": "11 components (Table, Badge, Avatar, Chart, etc.)", "feedback": "7 components (Alert, Toast, Progress, Spinner, etc.)", "navigation": "6 components (Tabs, Breadcrumb, Sidebar, etc.)", "overlay": "9 components (Dialog, Sheet, Dropdown, Tooltip, etc.)", "layout": "5 components (Card, Separator, Scroll Area, etc.)" }, "dependencies": { "radix": "26 Radix UI primitives", "additional": ["cmdk", "embla-carousel", "react-day-picker", "recharts", "sonner", "vaul"] } }, "changelog": [ {"version": "1.3.0", "date": "2025-12-10", "notes": "Add 59-component shadcn registry, expand primitives to full Tailwind palette"}, {"version": "1.2.0", "date": "2025-12-10", "notes": "Add 3-layer token architecture with skin contract validation"}, {"version": "1.1.0", "date": "2025-12-10", "notes": "Migrate from SQLite to JSON file storage"}, {"version": "1.0.0", "date": "2025-12-10", "notes": "Initial core definition"} ] }