bruno/dss
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Initial commit: Clean DSS implementation

Browse Source 
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm

Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)

Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability

Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
docs/principles/ATOMIC_HIERARCHY.md Normal file
View File

@@ -0,0 +1,294 @@
# DSS Atomic Hierarchy
> **The 5-level composition model for building design systems**
---
## Overview
The atomic hierarchy defines how design system elements compose from simple to complex. Each level builds upon the previous, creating a predictable structure.
```
Level 1: Tokens → Raw design values
Level 2: Primitives → Indivisible UI elements
Level 3: Components → Composite UI elements
Level 4: Layouts → Page structure patterns
Level 5: Views → Complete screens
```
---
## Level 1: Tokens
**Definition**: Design variables representing raw values.
Tokens are the foundation - the smallest unit of design decisions. They have no visual representation on their own.
### Categories
| Category | Purpose | Examples |
|----------|---------|----------|
| Colors | Color palette | `--color-primary-500`, `--color-neutral-100` |
| Typography | Font properties | `--font-size-md`, `--font-weight-bold` |
| Spacing | Whitespace scale | `--spacing-4`, `--spacing-8` |
| Sizing | Dimension values | `--size-button-height`, `--size-icon-md` |
| Borders | Border properties | `--border-radius-sm`, `--border-width-1` |
| Shadows | Elevation effects | `--shadow-sm`, `--shadow-lg` |
| Motion | Animation values | `--duration-fast`, `--easing-default` |
### Token Tiers
```
Primitive Tokens (raw values)
↓
Semantic Tokens (meaningful names)
↓
Component Tokens (scoped to components)
```
**Example**:
```css
/* Primitive */
--color-blue-500: #3b82f6;
/* Semantic */
--color-primary: var(--color-blue-500);
/* Component */
--button-background: var(--color-primary);
```
---
## Level 2: Primitives
**Definition**: Base UI elements that cannot be broken down further.
Primitives are the atoms of the design system. They implement tokens and provide the building blocks for components.
### Core Primitives
| Primitive | Description | Token Usage |
|-----------|-------------|-------------|
| Button | Clickable action trigger | colors, spacing, typography |
| Input | Text entry field | colors, spacing, borders |
| Label | Text descriptor | typography, colors |
| Icon | Visual symbol | sizing, colors |
| Badge | Status indicator | colors, typography, spacing |
| Divider | Visual separator | colors, spacing |
| Avatar | User representation | sizing, borders |
| Spinner | Loading indicator | sizing, colors, motion |
### Rules for Primitives
1. **Single responsibility** - One purpose per primitive
2. **Token-only styling** - No hardcoded values
3. **Stateless by default** - State managed externally
4. **Composable** - Designed for combination
5. **Accessible** - ARIA support built-in
---
## Level 3: Components
**Definition**: Composite UI elements combining multiple primitives.
Components solve specific UI problems by composing primitives into reusable patterns.
### Core Components
| Component | Primitives Used | Purpose |
|-----------|-----------------|---------|
| FormField | Label + Input + Icon | Complete form input |
| Card | Container + primitives | Content grouping |
| Modal | Container + Button + Icon | Overlay dialog |
| Dropdown | Button + List + Icon | Selection menu |
| Tabs | Button + Container | Content switching |
| Toast | Container + Icon + Button | Notifications |
| Tooltip | Container + Text | Contextual info |
### Component Patterns
**Compound Components**:
```jsx
<Card>
<Card.Header>Title</Card.Header>
<Card.Body>Content</Card.Body>
<Card.Footer>
<Button>Action</Button>
</Card.Footer>
</Card>
```
**Slot-based Components**:
```jsx
<FormField
label="Email"
input={<Input type="email" />}
error="Invalid email"
/>
```
### Rules for Components
1. **Compose primitives** - Never skip to tokens
2. **Define clear API** - Props, slots, events
3. **Handle state** - Internal state management
4. **Provide variants** - Size, color, style options
5. **Document usage** - Storybook stories required
---
## Level 4: Layouts
**Definition**: Page structure patterns that organize components.
Layouts define the spatial relationships and responsive behavior of page sections.
### Core Layouts
| Layout | Purpose | Components Used |
|--------|---------|-----------------|
| PageShell | App wrapper | Header, Sidebar, Content |
| DashboardGrid | Data display | Cards, Charts, Tables |
| FormLayout | Form organization | FormFields, Buttons |
| ListLayout | Item collections | Cards, Pagination |
| SplitView | Side-by-side | Panels, Dividers |
### Layout Primitives
```
Box → Basic container with spacing/sizing
Stack → Vertical arrangement with gap
Inline → Horizontal arrangement with gap
Grid → 2D arrangement with columns/rows
Cluster → Flexible wrapping arrangement
```
### Responsive Patterns
```css
/* Mobile-first breakpoints */
--breakpoint-sm: 640px; /* Phones */
--breakpoint-md: 768px; /* Tablets */
--breakpoint-lg: 1024px; /* Laptops */
--breakpoint-xl: 1280px; /* Desktops */
```
---
## Level 5: Views
**Definition**: Complete screens with content and functionality.
Views are the final composition - full pages that users interact with.
### DSS Admin Views
| View | Purpose | Layouts Used |
|------|---------|--------------|
| TokenExplorer | Browse/edit tokens | DashboardGrid |
| FigmaSync | Import from Figma | FormLayout |
| ComponentAudit | Review components | ListLayout |
| ThemeEditor | Customize themes | SplitView |
| Documentation | View docs | PageShell |
### View Responsibilities
1. **Data fetching** - API calls, state loading
2. **Route handling** - URL parameters, navigation
3. **Layout composition** - Arranging layouts
4. **Business logic** - Domain-specific rules
5. **Error boundaries** - Graceful failure handling
---
## Composition Rules
### The Golden Rule
> **Each level only references the level immediately below.**
```
Views → use Layouts (never tokens directly)
Layouts → use Components (never tokens directly)
Components → use Primitives (never tokens directly)
Primitives → use Tokens
Tokens → are the foundation
```
### Anti-Patterns
| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Token in View | Skips 4 levels | Use component with variant |
| Component in Token | Circular dependency | Tokens are values only |
| Layout without Components | Missing abstraction | Create component first |
| Primitive with business logic | Wrong responsibility | Move logic to component |
### Decision Tree
```
Need a design value?
→ Use a TOKEN
Need a single UI element?
→ Use a PRIMITIVE
Need a reusable UI pattern?
→ Create a COMPONENT
Need page structure?
→ Create a LAYOUT
Need a full screen?
→ Create a VIEW
```
---
## Implementation Examples
### Token → Primitive → Component → Layout → View
```
Token:
--color-primary: #3b82f6;
--spacing-4: 1rem;
Primitive:
<Button variant="primary">Click</Button>
(uses --color-primary, --spacing-4)
Component:
<FormField>
<Label>Email</Label>
<Input type="email" />
<Button type="submit">Send</Button>
</FormField>
Layout:
<FormLayout>
<FormField ... />
<FormField ... />
<FormField ... />
</FormLayout>
View:
<ContactPage>
<PageShell>
<FormLayout>
...
</FormLayout>
</PageShell>
</ContactPage>
```
---
## See Also
- [First Principles](./FIRST_PRINCIPLES.md) - Foundational truths
- [Glossary](../GLOSSARY.md) - Corporate terminology
- [Architecture Overview](../architecture/OVERVIEW.md) - 7-layer system

144
docs/principles/FIRST_PRINCIPLES.md Normal file
View File

@@ -0,0 +1,144 @@
# DSS First Principles
> **The 7 foundational truths that govern all design system decisions**
---
## Principle 1: Single Source of Truth
**Design tokens are the canonical representation of design decisions.**
- All outputs derive from tokens, never the reverse
- Tokens are immutable facts; themes are interpretations
- The database is the authoritative source for all token data
- External systems query DSS; DSS does not duplicate external state
```
Source (Figma/CSS/JSON) → DSS Tokens (truth) → Outputs (CSS/SCSS/TS)
```
---
## Principle 2: Atomic Composition
**Build complexity through composition, not complexity.**
The 5-level hierarchy:
1. **Tokens** - Design variables (colors, spacing, typography)
2. **Primitives** - Base UI elements (button, input, icon)
3. **Components** - Composite UI (form field, card)
4. **Layouts** - Page structure patterns
5. **Views** - Complete screens
**Rules:**
- Each level only references the level below
- Never skip levels (components don't directly use tokens without primitives)
- Composition creates complexity; primitives stay simple
---
## Principle 3: Separation of Concerns
**Keep distinct responsibilities in distinct places.**
| Concern | Separation |
|---------|------------|
| Definition vs Application | What tokens exist ≠ How they're used |
| Source vs Output | Where tokens come from ≠ What format they export to |
| Core vs Custom | Immutable DSS standards ≠ Client-specific extensions |
| Design vs Development | Token definition ≠ Token implementation |
---
## Principle 4: Translation Over Transformation
**External systems translate TO the design system, not the reverse.**
- Legacy code maps to canonical tokens via translation dictionaries
- Never modify core to accommodate edge cases
- Custom props live in client namespace, not DSS core
- The translation layer is explicit and auditable
```
Legacy CSS → Translation Dictionary → DSS Canonical Tokens
Figma → Translation Dictionary → DSS Canonical Tokens
```
---
## Principle 5: Observable Health
**Every layer must have measurable health indicators.**
- Validation happens at system boundaries
- Errors surface immediately with actionable context
- Metrics are collected at each layer
- Health status is queryable at any time
**Health Indicators by Layer:**
| Layer | Indicators |
|-------|------------|
| Core | Database connectivity, schema validity |
| Ingestion | Parse success rate, source availability |
| Validation | Error counts, warning counts |
| State | Token coverage, consistency scores |
| Processing | Transformation success, output validity |
| Presentation | Component coverage, story completeness |
| Integration | API latency, MCP tool availability |
---
## Principle 6: Progressive Enhancement
**Start minimal, scale through composition.**
1. Start with tokens (foundation)
2. Add components when tokens are stable
3. Add layouts when components are proven
4. Scale through composition, not complexity
**Anti-patterns to avoid:**
- Building components before defining tokens
- Creating layouts before components exist
- Adding features before foundations are solid
---
## Principle 7: Documentation as Code
**Documentation lives alongside implementation.**
- Every token has a reference
- Every component has a story
- Storybook is the living documentation
- Changes to code trigger changes to docs
- Documentation is versioned with code
```
Component Code + Story + Docs = Complete Delivery
```
---
## Application
When making design system decisions, ask:
1. Does this maintain a single source of truth?
2. Does this follow atomic composition?
3. Are concerns properly separated?
4. Are we translating TO DSS, not FROM it?
5. Can we observe the health of this change?
6. Are we enhancing progressively?
7. Is this documented alongside the code?
If any answer is "no", reconsider the approach.
---
## See Also
- [Glossary](../GLOSSARY.md) - Corporate terminology
- [Architecture Overview](../architecture/OVERVIEW.md) - 7-layer system
- [Atomic Hierarchy](./ATOMIC_HIERARCHY.md) - Composition rules