bruno/dss
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
280b5ee7a82378316841115b91569bc5a1f9e23b
dss/.knowledge/DSS_CORE.json
DSS 280b5ee7a8
Some checks failed
DSS Project Analysis / dss-context-update (push) Has been cancelled
Details
docs: Add core principle - development only, no deployment 
- DSS runs only in dev mode, no production deployment
- dss.overbits.luz.uy points to dev server
- Removed build step from setup (not needed)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-10 22:53:21 -03:00

321 lines
12 KiB
JSON
Raw Blame History

{
"$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)"
},
"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"}
]
}
Reference in New Issue View Git Blame Copy Permalink