novahiz 0.1.0

package/bundled-skills/ui-design-system/assets/design_system_doc_template.md

@@ -0,0 +1,180 @@
+# Design System Documentation
+
+## System Info
+
+| Field | Value |
+|-------|-------|
+| **Name** | [Design System Name] |
+| **Version** | [X.Y.Z] |
+| **Owner** | [Team/Person] |
+| **Status** | Active / Beta / Deprecated |
+| **Last Updated** | YYYY-MM-DD |
+
+---
+
+## Design Principles
+
+The following principles guide all design decisions in this system:
+
+1. **[Principle 1 Name]** - [One sentence description. Example: "Clarity over cleverness - every element should have an obvious purpose."]
+
+2. **[Principle 2 Name]** - [One sentence description. Example: "Consistency breeds confidence - similar actions should look and behave the same."]
+
+3. **[Principle 3 Name]** - [One sentence description. Example: "Accessible by default - every component must meet WCAG 2.1 AA standards."]
+
+4. **[Principle 4 Name]** - [One sentence description. Example: "Progressive disclosure - show only what is needed, reveal complexity on demand."]
+
+---
+
+## Color Palette
+
+### Brand Colors
+| Name | Hex | RGB | Usage |
+|------|-----|-----|-------|
+| Primary | #[XXXXXX] | rgb(X, X, X) | Primary actions, links, key UI elements |
+| Secondary | #[XXXXXX] | rgb(X, X, X) | Secondary actions, accents |
+| Accent | #[XXXXXX] | rgb(X, X, X) | Highlights, badges, notifications |
+
+### Neutral Colors
+| Name | Hex | Usage |
+|------|-----|-------|
+| Gray-900 | #[XXXXXX] | Primary text |
+| Gray-700 | #[XXXXXX] | Secondary text |
+| Gray-500 | #[XXXXXX] | Placeholder text, disabled states |
+| Gray-300 | #[XXXXXX] | Borders, dividers |
+| Gray-100 | #[XXXXXX] | Backgrounds, hover states |
+| White | #FFFFFF | Page background, card background |
+
+### Semantic Colors
+| Name | Hex | Usage |
+|------|-----|-------|
+| Success | #[XXXXXX] | Success messages, positive indicators |
+| Warning | #[XXXXXX] | Warning messages, caution indicators |
+| Error | #[XXXXXX] | Error messages, destructive actions |
+| Info | #[XXXXXX] | Informational messages, tips |
+
+### Accessibility
+- All text colors must meet WCAG 2.1 AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
+- Test with color blindness simulators
+- Never use color as the only indicator of state
+
+---
+
+## Typography Scale
+
+### Font Family
+- **Primary:** [Font Name] (headings and body)
+- **Monospace:** [Font Name] (code blocks, technical content)
+- **Fallback Stack:** [System font stack]
+
+### Type Scale
+
+| Name | Size | Weight | Line Height | Usage |
+|------|------|--------|-------------|-------|
+| Display | 48px / 3rem | Bold (700) | 1.2 | Hero headings |
+| H1 | 36px / 2.25rem | Bold (700) | 1.25 | Page titles |
+| H2 | 28px / 1.75rem | Semibold (600) | 1.3 | Section headings |
+| H3 | 22px / 1.375rem | Semibold (600) | 1.35 | Subsection headings |
+| H4 | 18px / 1.125rem | Medium (500) | 1.4 | Card titles, labels |
+| Body Large | 18px / 1.125rem | Regular (400) | 1.6 | Lead paragraphs |
+| Body | 16px / 1rem | Regular (400) | 1.5 | Default body text |
+| Body Small | 14px / 0.875rem | Regular (400) | 1.5 | Secondary text, captions |
+| Caption | 12px / 0.75rem | Regular (400) | 1.4 | Labels, metadata |
+
+---
+
+## Spacing System
+
+### Base Unit: 4px
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| space-1 | 4px | Tight spacing (icon padding) |
+| space-2 | 8px | Compact elements (inline items) |
+| space-3 | 12px | Related elements (form field gaps) |
+| space-4 | 16px | Default spacing (paragraph gaps) |
+| space-5 | 20px | Group spacing (card padding) |
+| space-6 | 24px | Section spacing |
+| space-8 | 32px | Large section gaps |
+| space-10 | 40px | Page section dividers |
+| space-12 | 48px | Major layout sections |
+| space-16 | 64px | Page-level spacing |
+
+### Layout Spacing
+- **Page margin:** space-6 (mobile), space-8 (tablet), space-12 (desktop)
+- **Card padding:** space-5
+- **Form field gap:** space-3
+- **Section gap:** space-10
+
+---
+
+## Component Library
+
+### Component Status Legend
+- **Stable** - Production ready, fully documented and tested
+- **Beta** - Functional but may change, use with awareness
+- **Deprecated** - Scheduled for removal, migrate to replacement
+- **Planned** - On roadmap, not yet available
+
+### Components
+
+| Component | Status | Description | Variants |
+|-----------|--------|-------------|----------|
+| Button | Stable | Primary action triggers | Primary, Secondary, Tertiary, Danger, Ghost |
+| Input | Stable | Text input fields | Default, Error, Disabled, With icon |
+| Select | Stable | Dropdown selection | Single, Multi, Searchable |
+| Checkbox | Stable | Multi-select toggle | Default, Indeterminate, Disabled |
+| Radio | Stable | Single-select option | Default, Disabled |
+| Toggle | Stable | Binary on/off switch | Default, With label |
+| Modal | Stable | Overlay dialog | Small, Medium, Large, Fullscreen |
+| Toast | Stable | Temporary notification | Success, Error, Warning, Info |
+| Card | Stable | Content container | Default, Interactive, Elevated |
+| Badge | Stable | Status indicator | Solid, Outline, Dot |
+| Avatar | Stable | User representation | Image, Initials, Icon |
+| Table | Beta | Data display grid | Default, Sortable, Selectable |
+| Tabs | Beta | Content organization | Default, Underline, Pill |
+| Tooltip | Stable | Contextual information | Default, Rich content |
+| [New Component] | Planned | [Description] | [Variants] |
+
+---
+
+## Usage Guidelines
+
+### Do
+- Use components as documented (do not override internal styles)
+- Follow the spacing system for consistent layouts
+- Test components across supported browsers and screen sizes
+- Use semantic colors for their intended purpose
+- Reference design tokens instead of hardcoded values
+
+### Do Not
+- Modify component internals without contributing changes back
+- Create one-off components when an existing component fits
+- Use brand colors for semantic purposes (error, success)
+- Skip accessibility requirements for "internal" tools
+- Mix design system versions across a single application
+
+---
+
+## Contribution Process
+
+### Proposing a New Component
+1. **Check existing components** - Verify no existing component solves the need
+2. **Create proposal** - Document use case, behavior, variants, accessibility requirements
+3. **Design review** - Present to design system team for feedback
+4. **Build** - Implement component following system patterns
+5. **Review** - Code review + design review + accessibility audit
+6. **Document** - Add to component library with usage guidelines
+7. **Release** - Publish in next minor version
+
+### Updating an Existing Component
+1. **File issue** - Describe the change and justification
+2. **Impact assessment** - Identify all instances of current usage
+3. **Design + develop** - Implement change with backward compatibility
+4. **Migration guide** - Document breaking changes if any
+5. **Release** - Publish with changelog entry
+
+### Reporting Issues
+- File bug reports with reproduction steps and screenshots
+- Tag with component name and severity
+- Include browser/OS information for rendering issues

package/bundled-skills/ui-design-system/references/component-architecture.md

@@ -0,0 +1,396 @@
+# Component Architecture Guide
+
+Reference for design system component organization, naming conventions, and documentation patterns.
+
+---
+
+## Table of Contents
+
+- [Component Hierarchy](#component-hierarchy)
+- [Naming Conventions](#naming-conventions)
+- [Component Documentation](#component-documentation)
+- [Variant Patterns](#variant-patterns)
+- [Token Integration](#token-integration)
+
+---
+
+## Component Hierarchy
+
+### Atomic Design Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    COMPONENT HIERARCHY                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  TOKENS (Foundation)                                        │
+│    └── Colors, Typography, Spacing, Shadows                 │
+│                                                             │
+│  ATOMS (Basic Elements)                                     │
+│    └── Button, Input, Icon, Label, Badge                    │
+│                                                             │
+│  MOLECULES (Simple Combinations)                            │
+│    └── FormField, SearchBar, Card, ListItem                 │
+│                                                             │
+│  ORGANISMS (Complex Components)                             │
+│    └── Header, Footer, DataTable, Modal                     │
+│                                                             │
+│  TEMPLATES (Page Layouts)                                   │
+│    └── DashboardLayout, AuthLayout, SettingsLayout          │
+│                                                             │
+│  PAGES (Specific Instances)                                 │
+│    └── HomePage, LoginPage, UserProfile                     │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Component Categories
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| **Primitives** | Base HTML wrapper | Box, Text, Flex, Grid |
+| **Inputs** | User interaction | Button, Input, Select, Checkbox |
+| **Display** | Content presentation | Card, Badge, Avatar, Icon |
+| **Feedback** | User feedback | Alert, Toast, Progress, Skeleton |
+| **Navigation** | Route management | Link, Menu, Tabs, Breadcrumb |
+| **Overlay** | Layer above content | Modal, Drawer, Popover, Tooltip |
+| **Layout** | Structure | Stack, Container, Divider |
+
+---
+
+## Naming Conventions
+
+### Token Naming
+
+```
+{category}-{property}-{variant}-{state}
+
+Examples:
+  color-primary-500
+  color-primary-500-hover
+  spacing-md
+  fontSize-lg
+  shadow-md
+  radius-lg
+```
+
+### Component Naming
+
+```
+{ComponentName}             # PascalCase for components
+{componentName}{Variant}    # Variant suffix
+
+Examples:
+  Button
+  ButtonPrimary
+  ButtonOutline
+  ButtonGhost
+```
+
+### CSS Class Naming (BEM)
+
+```
+.block__element--modifier
+
+Examples:
+  .button
+  .button__icon
+  .button--primary
+  .button--lg
+  .button__icon--loading
+```
+
+### File Structure
+
+```
+components/
+├── Button/
+│   ├── Button.tsx           # Main component
+│   ├── Button.styles.ts     # Styles/tokens
+│   ├── Button.test.tsx      # Tests
+│   ├── Button.stories.tsx   # Storybook
+│   ├── Button.types.ts      # TypeScript types
+│   └── index.ts             # Export
+├── Input/
+│   └── ...
+└── index.ts                 # Barrel export
+```
+
+---
+
+## Component Documentation
+
+### Documentation Template
+
+```markdown
+# ComponentName
+
+Brief description of what this component does.
+
+## Usage
+
+\`\`\`tsx
+import { Button } from '@design-system/components'
+
+<Button variant="primary" size="md">
+  Click me
+</Button>
+\`\`\`
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Component size |
+| disabled | boolean | false | Disabled state |
+| onClick | () => void | - | Click handler |
+
+## Variants
+
+### Primary
+Use for main actions.
+
+### Secondary
+Use for secondary actions.
+
+### Ghost
+Use for tertiary or inline actions.
+
+## Accessibility
+
+- Uses `button` role by default
+- Supports `aria-disabled` for disabled state
+- Focus ring visible for keyboard navigation
+
+## Design Tokens Used
+
+- `color-primary-*` for primary variant
+- `spacing-*` for padding
+- `radius-md` for border radius
+- `shadow-sm` for elevation
+```
+
+### Props Interface Pattern
+
+```typescript
+interface ButtonProps {
+  /** Visual variant of the button */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+
+  /** Size of the button */
+  size?: 'sm' | 'md' | 'lg';
+
+  /** Whether button is disabled */
+  disabled?: boolean;
+
+  /** Whether button shows loading state */
+  loading?: boolean;
+
+  /** Left icon element */
+  leftIcon?: React.ReactNode;
+
+  /** Right icon element */
+  rightIcon?: React.ReactNode;
+
+  /** Click handler */
+  onClick?: () => void;
+
+  /** Button content */
+  children: React.ReactNode;
+}
+```
+
+---
+
+## Variant Patterns
+
+### Size Variants
+
+```typescript
+const sizeTokens = {
+  sm: {
+    height: 'sizing-button-sm-height',    // 32px
+    paddingX: 'sizing-button-sm-paddingX', // 12px
+    fontSize: 'fontSize-sm',               // 14px
+    iconSize: 'sizing-icon-sm'             // 16px
+  },
+  md: {
+    height: 'sizing-button-md-height',    // 40px
+    paddingX: 'sizing-button-md-paddingX', // 16px
+    fontSize: 'fontSize-base',             // 16px
+    iconSize: 'sizing-icon-md'             // 20px
+  },
+  lg: {
+    height: 'sizing-button-lg-height',    // 48px
+    paddingX: 'sizing-button-lg-paddingX', // 20px
+    fontSize: 'fontSize-lg',               // 18px
+    iconSize: 'sizing-icon-lg'             // 24px
+  }
+};
+```
+
+### Color Variants
+
+```typescript
+const variantTokens = {
+  primary: {
+    background: 'color-primary-500',
+    backgroundHover: 'color-primary-600',
+    backgroundActive: 'color-primary-700',
+    text: 'color-white',
+    border: 'transparent'
+  },
+  secondary: {
+    background: 'color-neutral-100',
+    backgroundHover: 'color-neutral-200',
+    backgroundActive: 'color-neutral-300',
+    text: 'color-neutral-900',
+    border: 'transparent'
+  },
+  outline: {
+    background: 'transparent',
+    backgroundHover: 'color-primary-50',
+    backgroundActive: 'color-primary-100',
+    text: 'color-primary-500',
+    border: 'color-primary-500'
+  },
+  ghost: {
+    background: 'transparent',
+    backgroundHover: 'color-neutral-100',
+    backgroundActive: 'color-neutral-200',
+    text: 'color-neutral-700',
+    border: 'transparent'
+  }
+};
+```
+
+### State Variants
+
+```typescript
+const stateStyles = {
+  default: {
+    cursor: 'pointer',
+    opacity: 1
+  },
+  hover: {
+    // Uses variantTokens backgroundHover
+  },
+  active: {
+    // Uses variantTokens backgroundActive
+    transform: 'scale(0.98)'
+  },
+  focus: {
+    outline: 'none',
+    boxShadow: '0 0 0 2px color-primary-200'
+  },
+  disabled: {
+    cursor: 'not-allowed',
+    opacity: 0.5,
+    pointerEvents: 'none'
+  },
+  loading: {
+    cursor: 'wait',
+    pointerEvents: 'none'
+  }
+};
+```
+
+---
+
+## Token Integration
+
+### Consuming Tokens in Components
+
+**CSS Custom Properties:**
+
+```css
+.button {
+  height: var(--sizing-button-md-height);
+  padding-left: var(--sizing-button-md-paddingX);
+  padding-right: var(--sizing-button-md-paddingX);
+  font-size: var(--typography-fontSize-base);
+  border-radius: var(--borders-radius-md);
+}
+
+.button--primary {
+  background-color: var(--colors-primary-500);
+  color: var(--colors-surface-background);
+}
+
+.button--primary:hover {
+  background-color: var(--colors-primary-600);
+}
+```
+
+**JavaScript/TypeScript:**
+
+```typescript
+import tokens from './design-tokens.json';
+
+const buttonStyles = {
+  height: tokens.sizing.components.button.md.height,
+  paddingLeft: tokens.sizing.components.button.md.paddingX,
+  backgroundColor: tokens.colors.primary['500'],
+  borderRadius: tokens.borders.radius.md
+};
+```
+
+**Styled Components:**
+
+```typescript
+import styled from 'styled-components';
+
+const Button = styled.button`
+  height: ${({ theme }) => theme.sizing.components.button.md.height};
+  padding: 0 ${({ theme }) => theme.sizing.components.button.md.paddingX};
+  background: ${({ theme }) => theme.colors.primary['500']};
+  border-radius: ${({ theme }) => theme.borders.radius.md};
+
+  &:hover {
+    background: ${({ theme }) => theme.colors.primary['600']};
+  }
+`;
+```
+
+### Token-to-Component Mapping
+
+| Component | Token Categories Used |
+|-----------|----------------------|
+| Button | colors, sizing, borders, shadows, typography |
+| Input | colors, sizing, borders, spacing |
+| Card | colors, borders, shadows, spacing |
+| Typography | typography (all), colors |
+| Icon | sizing, colors |
+| Modal | colors, shadows, spacing, z-index, animation |
+
+---
+
+## Component Checklist
+
+### Before Release
+
+- [ ] All sizes implemented (sm, md, lg)
+- [ ] All variants implemented (primary, secondary, etc.)
+- [ ] All states working (hover, active, focus, disabled)
+- [ ] Keyboard accessible
+- [ ] Screen reader tested
+- [ ] Uses only design tokens (no hardcoded values)
+- [ ] TypeScript types complete
+- [ ] Storybook stories for all variants
+- [ ] Unit tests passing
+- [ ] Documentation complete
+
+### Accessibility Checklist
+
+- [ ] Correct semantic HTML element
+- [ ] ARIA attributes where needed
+- [ ] Visible focus indicator
+- [ ] Color contrast meets AA
+- [ ] Works with keyboard only
+- [ ] Screen reader announces correctly
+- [ ] Touch target ≥ 44×44px
+
+---
+
+*See also: `token-generation.md` for token creation*