Initial commit: Clean DSS implementation
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
391
admin-ui/COMPONENT-USAGE.md
Normal file
391
admin-ui/COMPONENT-USAGE.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# Component Usage Guide
|
||||
|
||||
How to use design system components in the DSS Admin UI and other projects.
|
||||
|
||||
## Navigation Components
|
||||
|
||||
### Navigation Sections
|
||||
|
||||
Group related navigation items with section headers.
|
||||
|
||||
```html
|
||||
<div class="nav-section">
|
||||
<h3 class="nav-section__title">Main</h3>
|
||||
<a href="#dashboard" class="nav-item" data-page="dashboard">
|
||||
<svg class="nav-item__icon"><!-- icon --></svg>
|
||||
Dashboard
|
||||
</a>
|
||||
<a href="#analytics" class="nav-item" data-page="analytics">
|
||||
<svg class="nav-item__icon"><!-- icon --></svg>
|
||||
Analytics
|
||||
</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Classes**:
|
||||
- `.nav-section`: Container for related items
|
||||
- `.nav-section__title`: Section header (uppercase, muted)
|
||||
- `.nav-item`: Individual navigation item
|
||||
- `.nav-item__icon`: Icon within navigation item
|
||||
- `.nav-item.active`: Active/current page state
|
||||
- `.nav-item--indent-1`: Indentation level 1
|
||||
- `.nav-item--indent-2`: Indentation level 2
|
||||
|
||||
**States**:
|
||||
- `:hover`: Light background, darker text
|
||||
- `:focus-visible`: Ring outline at 2px offset
|
||||
- `.active`: Primary background, lighter text
|
||||
|
||||
## Buttons
|
||||
|
||||
### Button Variants
|
||||
|
||||
```html
|
||||
<!-- Primary button -->
|
||||
<button class="btn-primary">Save Changes</button>
|
||||
|
||||
<!-- Secondary button -->
|
||||
<button class="btn-secondary">Cancel</button>
|
||||
|
||||
<!-- Ghost button -->
|
||||
<button class="btn-ghost">Learn More</button>
|
||||
|
||||
<!-- Destructive button -->
|
||||
<button class="btn-destructive">Delete</button>
|
||||
```
|
||||
|
||||
**Variants**:
|
||||
- `.btn-primary`: Main call-to-action
|
||||
- `.btn-secondary`: Secondary action
|
||||
- `.btn-ghost`: Tertiary action
|
||||
- `.btn-destructive`: Dangerous action (delete, remove)
|
||||
|
||||
**Sizes**:
|
||||
- `.btn-sm`: Small button (compact UI)
|
||||
- (default): Standard button
|
||||
- `.btn-lg`: Large button (primary CTA)
|
||||
|
||||
**States**:
|
||||
- `:hover`: Darker background
|
||||
- `:active`: Darkest background
|
||||
- `:disabled`: Reduced opacity, cursor not-allowed
|
||||
- `:focus-visible`: Ring outline
|
||||
|
||||
## Form Controls
|
||||
|
||||
### Input Fields
|
||||
|
||||
```html
|
||||
<div class="form-group">
|
||||
<label for="project-name">Project Name</label>
|
||||
<input type="text" id="project-name" placeholder="Enter name...">
|
||||
<div class="form-group__help">Used in URLs and API calls</div>
|
||||
</div>
|
||||
|
||||
<div class="form-group">
|
||||
<label for="description">Description</label>
|
||||
<textarea id="description" placeholder="Describe your project..."></textarea>
|
||||
</div>
|
||||
|
||||
<div class="form-group">
|
||||
<label for="team">Team</label>
|
||||
<select id="team">
|
||||
<option>Select a team...</option>
|
||||
<option>Design</option>
|
||||
<option>Engineering</option>
|
||||
</select>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Classes**:
|
||||
- `.form-group`: Container for input + label
|
||||
- `.form-group__help`: Helper text (muted)
|
||||
- `.form-group__error`: Error message (destructive color)
|
||||
|
||||
**Input Types**:
|
||||
- `input[type="text"]`
|
||||
- `input[type="email"]`
|
||||
- `input[type="password"]`
|
||||
- `textarea`
|
||||
- `select`
|
||||
|
||||
**States**:
|
||||
- `:focus`: Border to ring color
|
||||
- `:disabled`: Muted background
|
||||
- `.form-group__error`: Display error below input
|
||||
|
||||
## Cards & Panels
|
||||
|
||||
### Basic Card
|
||||
|
||||
```html
|
||||
<div class="card">
|
||||
<h3>Card Title</h3>
|
||||
<p>Card content goes here.</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Card Variants
|
||||
|
||||
```html
|
||||
<!-- Elevated card -->
|
||||
<div class="card card--elevated">
|
||||
Content with shadow
|
||||
</div>
|
||||
|
||||
<!-- Outlined card -->
|
||||
<div class="card card--outlined">
|
||||
Content with border only
|
||||
</div>
|
||||
```
|
||||
|
||||
### Panel with Structure
|
||||
|
||||
```html
|
||||
<div class="panel">
|
||||
<div class="panel__header">
|
||||
<h3 class="panel__title">Panel Title</h3>
|
||||
<button class="btn-ghost">Close</button>
|
||||
</div>
|
||||
<div class="panel__body">
|
||||
Panel content goes here
|
||||
</div>
|
||||
<div class="panel__footer">
|
||||
<button class="btn-secondary">Cancel</button>
|
||||
<button class="btn-primary">Save</button>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Classes**:
|
||||
- `.card`: Basic card container
|
||||
- `.card--elevated`: Card with shadow
|
||||
- `.card--outlined`: Card with border
|
||||
- `.panel`: Structured container
|
||||
- `.panel__header`: Header section with title
|
||||
- `.panel__title`: Panel heading
|
||||
- `.panel__body`: Main content area
|
||||
- `.panel__footer`: Footer with actions
|
||||
|
||||
## Help Panel (Collapsible)
|
||||
|
||||
```html
|
||||
<details class="help-panel">
|
||||
<summary class="help-panel__toggle">
|
||||
<svg><!-- help icon --></svg>
|
||||
Need Help?
|
||||
</summary>
|
||||
<div class="help-panel__content">
|
||||
<div class="help-section">
|
||||
<strong>Getting Started</strong>
|
||||
<ul>
|
||||
<li>Create a new project</li>
|
||||
<li>Import design tokens</li>
|
||||
<li>Apply to your UI</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="help-section">
|
||||
<strong>Keyboard Shortcuts</strong>
|
||||
<ul>
|
||||
<li><code>Cmd+K</code>: Search</li>
|
||||
<li><code>Cmd+/</code>: Toggle sidebar</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</details>
|
||||
```
|
||||
|
||||
**Classes**:
|
||||
- `.help-panel`: Details element wrapper
|
||||
- `.help-panel__toggle`: Summary (clickable title)
|
||||
- `.help-panel__content`: Content container (hidden by default)
|
||||
- `.help-section`: Section within content
|
||||
- `<strong>`: Section header
|
||||
|
||||
**States**:
|
||||
- `.help-panel[open]`: Content visible
|
||||
|
||||
## Notification Indicator
|
||||
|
||||
```html
|
||||
<button class="notification-toggle-container">
|
||||
<svg><!-- bell icon --></svg>
|
||||
<span class="status-dot"></span>
|
||||
</button>
|
||||
```
|
||||
|
||||
**Classes**:
|
||||
- `.notification-toggle-container`: Container for relative positioning
|
||||
- `.status-dot`: Small indicator dot
|
||||
|
||||
## Utility Classes
|
||||
|
||||
### Flexbox
|
||||
|
||||
```html
|
||||
<!-- Flex container -->
|
||||
<div class="flex gap-4">
|
||||
<div>Left</div>
|
||||
<div>Right</div>
|
||||
</div>
|
||||
|
||||
<!-- Column layout -->
|
||||
<div class="flex flex-col gap-2">
|
||||
<div>Top</div>
|
||||
<div>Middle</div>
|
||||
<div>Bottom</div>
|
||||
</div>
|
||||
|
||||
<!-- Centering -->
|
||||
<div class="flex items-center justify-center">
|
||||
Centered content
|
||||
</div>
|
||||
```
|
||||
|
||||
**Flex Utilities**:
|
||||
- `.flex`: Display flex
|
||||
- `.flex-col`: Flex direction column
|
||||
- `.flex-row`: Flex direction row (default)
|
||||
- `.justify-start`, `.justify-center`, `.justify-end`, `.justify-between`, `.justify-around`
|
||||
- `.items-start`, `.items-center`, `.items-end`
|
||||
|
||||
### Gaps & Spacing
|
||||
|
||||
```html
|
||||
<div class="gap-4 p-4 m-3">
|
||||
Content with gap, padding, margin
|
||||
</div>
|
||||
```
|
||||
|
||||
**Gap Utilities**: `.gap-1` through `.gap-6`
|
||||
**Padding**: `.p-1`, `.p-2`, `.p-3`, `.p-4`, `.p-6`
|
||||
**Margin**: `.m-1`, `.m-2`, `.m-3`, `.m-4`, `.m-6`
|
||||
|
||||
### Text & Typography
|
||||
|
||||
```html
|
||||
<p class="text-sm text-muted">Small muted text</p>
|
||||
<h2 class="text-xl font-600">Heading</h2>
|
||||
<p class="text-primary">Colored text</p>
|
||||
```
|
||||
|
||||
**Text Size**: `.text-xs` through `.text-2xl`
|
||||
**Font Weight**: `.font-400` through `.font-700`
|
||||
**Text Color**: `.text-foreground`, `.text-muted`, `.text-primary`, `.text-destructive`, `.text-success`, `.text-warning`
|
||||
|
||||
### Background & Borders
|
||||
|
||||
```html
|
||||
<div class="bg-surface border rounded p-4">
|
||||
Styled container
|
||||
</div>
|
||||
```
|
||||
|
||||
**Background**: `.bg-surface`, `.bg-muted`, `.bg-primary`, `.bg-destructive`
|
||||
**Border**: `.border`, `.border-none`, `.border-top`, `.border-bottom`
|
||||
**Border Radius**: `.rounded`, `.rounded-sm`, `.rounded-md`, `.rounded-lg`, `.rounded-full`
|
||||
|
||||
### Display & Visibility
|
||||
|
||||
```html
|
||||
<div class="hidden">Not visible</div>
|
||||
<div class="block">Block element</div>
|
||||
<div class="inline-block">Inline-block element</div>
|
||||
```
|
||||
|
||||
**Display**: `.hidden`, `.block`, `.inline-block`, `.inline`
|
||||
**Overflow**: `.overflow-hidden`, `.overflow-auto`, `.overflow-x-auto`, `.overflow-y-auto`
|
||||
**Opacity**: `.opacity-50`, `.opacity-75`, `.opacity-100`
|
||||
|
||||
## Responsive Design
|
||||
|
||||
Media queries are handled in Layer 5 (`_responsive.css`):
|
||||
|
||||
```css
|
||||
/* Tablets and below */
|
||||
@media (max-width: 1023px) {
|
||||
.sidebar {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
/* Mobile only */
|
||||
@media (max-width: 639px) {
|
||||
button {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Breakpoints**:
|
||||
- `1024px`: Tablet/desktop boundary
|
||||
- `640px`: Mobile/tablet boundary
|
||||
|
||||
## Accessible Components
|
||||
|
||||
All components are built with accessibility in mind:
|
||||
|
||||
### Focus Management
|
||||
```html
|
||||
<!-- Input gets focus ring -->
|
||||
<input type="text" />
|
||||
|
||||
<!-- Button gets focus ring -->
|
||||
<button>Action</button>
|
||||
```
|
||||
|
||||
### Labels for Inputs
|
||||
```html
|
||||
<!-- Always pair label with input -->
|
||||
<label for="email">Email Address</label>
|
||||
<input type="email" id="email" />
|
||||
```
|
||||
|
||||
### Navigation Semantics
|
||||
```html
|
||||
<nav class="sidebar__nav">
|
||||
<div class="nav-section">
|
||||
<!-- Items get proper keyboard nav -->
|
||||
</div>
|
||||
</nav>
|
||||
```
|
||||
|
||||
### Color Contrast
|
||||
- All text meets WCAG AA or AAA standards
|
||||
- Never rely on color alone to convey information
|
||||
|
||||
### Motion Preferences
|
||||
Consider user preferences:
|
||||
```css
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
* {
|
||||
animation-duration: 0.01ms !important;
|
||||
transition-duration: 0.01ms !important;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dark Mode
|
||||
|
||||
All components automatically respond to dark mode:
|
||||
|
||||
```css
|
||||
@media (prefers-color-scheme: dark) {
|
||||
/* Dark theme colors applied automatically */
|
||||
}
|
||||
```
|
||||
|
||||
Users can also set theme explicitly:
|
||||
```html
|
||||
<html data-theme="dark">
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use semantic HTML**: `<button>`, `<input>`, `<label>`, `<nav>`
|
||||
2. **Combine utilities**: Mix classes for flexibility
|
||||
3. **Maintain spacing consistency**: Always use spacing scale
|
||||
4. **Test contrast**: Especially for custom colors
|
||||
5. **Keyboard test**: Ensure all interactive elements are keyboard accessible
|
||||
6. **Mobile first**: Design for mobile, enhance for larger screens
|
||||
7. **Respect motion preferences**: Reduce animations for users who prefer it
|
||||
Reference in New Issue
Block a user