@schilling.mark.a/software-methodology 1.0.0

package/ui-design-system/references/components.md

@@ -0,0 +1,257 @@
+# Components
+
+## Component Catalog
+
+Every standard component is specified here. When implementing, match the spec exactly. When a component is missing from this catalog, consult ui-design-workflow's `references/component-selection.md` to decide whether to create one.
+
+---
+
+## Button
+
+### Variants
+
+| Variant | Use | Background | Text | Border |
+|---|---|---|---|---|
+| Primary | Main CTA, one per screen | color.brand.primary.default | color.text.inverse | none |
+| Secondary | Supporting action | color.surface.card | color.text.primary | border.color.default |
+| Ghost | Tertiary action, inline | transparent | color.brand.primary.default | none |
+| Danger | Destructive action | color.feedback.error.default | color.text.inverse | none |
+
+### Sizes
+
+| Size | Height | Padding (H) | Font | Use |
+|---|---|---|---|---|
+| sm | 32px | spacing.md | type.body.sm | Compact contexts, tables |
+| md | 40px | spacing.lg | type.body.md | Default |
+| lg | 48px | spacing.xl | type.body.lg | Hero CTAs, landing pages |
+
+### States
+
+- **Hover:** background shifts one step darker on the scale
+- **Active/Pressed:** background shifts two steps darker
+- **Focus:** border.width.medium ring in border.color.focus, offset 2px
+- **Disabled:** opacity 0.4, cursor not-allowed, no hover/active states
+- **Loading:** show spinner, disable interaction, maintain width
+
+### Rules
+- One primary button per screen (or per logical section)
+- Icon + label preferred over label alone for clarity
+- Never use a button for navigation — use a link
+
+---
+
+## Input
+
+### Variants
+
+| Variant | Use |
+|---|---|
+| Text | Single-line free text |
+| Textarea | Multi-line text (min 3 rows) |
+| Number | Numeric values |
+| Password | Masked input |
+| Select | Single choice from a list |
+| Multi-select | Multiple choices from a list |
+
+### Anatomy
+
+```
+[Label]                          ← type.label, color.text.primary
+[Input field]                    ← border.radius.sm, border.color.default
+[Helper text — optional]         ← type.body.sm, color.text.secondary
+[Error message — replaces helper when invalid] ← type.body.sm, color.feedback.error.text
+```
+
+### States
+
+- **Default:** border.color.default, border.width.thin
+- **Hover:** border.color.hover
+- **Focus:** border.color.focus, border.width.medium
+- **Filled:** same as default (no visual change just because it has a value)
+- **Disabled:** background color.neutral.100, text color.text.disabled, border color.neutral.100
+- **Error:** border color.feedback.error.border, error message visible below
+
+### Rules
+- Label is always visible. Never use placeholder as the label.
+- Placeholder text is supplementary only — what to type, not what the field is for.
+- Required fields: append ` *` to the label. Explain what `*` means once per form.
+- Error messages are inline, directly below the field that failed. Never at the top of the form alone.
+
+---
+
+## Alert / Banner
+
+### Variants
+
+| Variant | Icon | Background | Border | Use |
+|---|---|---|---|---|
+| Error | ✕ circle | color.feedback.error.default (light) | color.feedback.error.default | Form-level errors, failed operations |
+| Success | ✓ circle | color.feedback.success.default (light) | color.feedback.success.default | Completed operations |
+| Warning | ! triangle | color.feedback.warning.default (light) | color.feedback.warning.default | Non-blocking cautions |
+| Info | ℹ circle | color.feedback.info.default (light) | color.feedback.info.default | Contextual information |
+
+### Anatomy
+
+```
+[Icon]  [Title — type.label]
+        [Message — type.body.sm]
+        [Action link — optional]
+```
+
+### Rules
+- Alerts are for messages that need user attention. Not for decoration.
+- Dismissible alerts have a close button (top-right corner).
+- Page-level alerts sit directly below the page header.
+- Inline alerts sit within the content, near the context they describe.
+
+---
+
+## Table
+
+### Structure
+
+```
+┌──────────┬──────────┬──────────┬──────────┐
+│ Header   │ Header   │ Header   │ Header   │  ← type.label, color.neutral.500, border-bottom
+├──────────┼──────────┼──────────┼──────────┤     border.width.medium
+│ Cell     │ Cell     │ Cell     │ Cell     │  ← type.body.md, color.text.primary
+├──────────┼──────────┼──────────┼──────────┤     border-bottom border.width.thin
+│ Cell     │ Cell     │ Cell     │ Cell     │
+└──────────┴──────────┴──────────┴──────────┘
+```
+
+### States
+
+- **Row hover:** background color.neutral.100
+- **Row selected:** background color.brand.primary (very light tint), left border accent
+- **Sortable column:** header shows sort indicator (↑↓ default, ↑ asc, ↓ desc)
+- **Empty:** full-width row with centered empty state message
+
+### Rules
+- Right-align numeric columns. Left-align everything else.
+- Truncate long cell content with ellipsis. Tooltip on hover shows full value.
+- On mobile (xs), tables become horizontal-scroll or collapse to card stacks.
+- First column is always a text identifier — never an action column.
+
+---
+
+## Card
+
+### Anatomy
+
+```
+┌─────────────────────────────┐
+│  [Image — optional, full-width top]  │
+├─────────────────────────────┤
+│  [Title — type.h4]          │  ← padding: spacing.lg all sides
+│  [Subtitle — type.body.sm]  │
+│                             │
+│  [Content]                  │
+│                             │
+│  [Actions — bottom-aligned] │
+└─────────────────────────────┘
+```
+
+### Styles
+
+- Background: color.surface.card
+- Border: border.width.thin, border.color.default
+- Radius: border.radius.md
+- Elevation: elevation.1 at rest, elevation.2 on hover (if clickable)
+- Padding: spacing.lg (24px) all sides
+
+### Rules
+- Cards at the same level use the same size. No mixed heights in a grid.
+- If a card is clickable, the entire card is the click target — not just the title.
+- Clickable cards show elevation change on hover. Non-clickable cards do not.
+- Limit to 3–4 content elements per card. More = use a detail page instead.
+
+---
+
+## Navigation Bar
+
+### Top Nav (desktop)
+
+```
+[Logo]  [Nav Item] [Nav Item] [Nav Item]          [User Avatar] [Action]
+        ^^^^^^^^^^^^
+        Active item: color.brand.primary, border-bottom border.width.medium
+```
+
+### Sidebar Nav (mobile or app-style)
+
+```
+┌──────────────┐
+│ [Logo]       │
+│              │
+│ [Nav Item]   │  ← type.body.md, color.text.primary
+│ [Nav Item]   │  ← active: background color.neutral.100, left border accent
+│ [Nav Item]   │
+│   [Sub Item] │  ← indented spacing.lg, type.body.sm
+│              │
+│ ──────────── │
+│ [Nav Item]   │  ← secondary group, separated by divider
+└──────────────┘
+```
+
+### Rules
+- Active item is always visually distinct — never ambiguous.
+- Nav items use ubiquitous language. Match the story map activity names.
+- Maximum depth: two levels (item + sub-item). No deeper nesting.
+- Mobile: hamburger menu opens a full-screen or drawer sidebar.
+
+---
+
+## Modal
+
+### Anatomy
+
+```
+┌─── Overlay (color.surface.overlay, 50% opacity) ───┐
+│                                                     │
+│   ┌──────────────────────────────────┐              │
+│   │  [Title — type.h3]      [✕ Close]│              │
+│   │  ────────────────────────────    │              │
+│   │  [Content]                       │              │
+│   │                                  │              │
+│   │  [Cancel]  [Primary Action]      │  ← actions bottom-right
+│   └──────────────────────────────────┘              │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+### Sizes
+
+| Size | Width | Use |
+|---|---|---|
+| sm | 400px | Confirmations, simple forms |
+| md | 600px | Standard forms, detail views |
+| lg | 800px | Complex forms, data entry |
+| xl | 90vw (max 1000px) | Wizards, multi-step flows |
+
+### Rules
+- Focus traps inside the modal. Tab cycles within it. Escape closes it.
+- Always provide a close button (✕) AND a cancel action button.
+- Modals block the page. Use sparingly — prefer inline editing or dedicated pages for complex flows.
+- Confirmation modals: state what will happen clearly. Destructive action button is Danger variant.
+- On mobile, modals become full-screen or bottom sheets.
+
+---
+
+## Badge / Tag
+
+### Variants
+
+| Variant | Background | Text | Use |
+|---|---|---|---|
+| Default | color.neutral.100 | color.text.primary | Neutral labels |
+| Primary | color.brand.primary (light) | color.brand.primary.default | Active, featured |
+| Success | color.feedback.success.default (light) | color.feedback.success.text | Completed, active |
+| Error | color.feedback.error.default (light) | color.feedback.error.text | Failed, blocked |
+| Warning | color.feedback.warning.default (light) | color.feedback.warning.text | Pending, caution |
+
+### Rules
+- Badges are labels, not actions. They don't do anything when clicked (unless explicitly linked).
+- Text: type.caption or type.overline. Never larger.
+- Radius: border.radius.full (pill shape) for status badges. border.radius.sm for category tags.
+- Maximum 3 badges visible at once. More = use a "+N more" indicator.

package/ui-design-system/references/design-tokens.md

@@ -0,0 +1,209 @@
+# Design Tokens
+
+## What Are Design Tokens?
+
+Named values that represent every visual decision in the system. Code references tokens, never raw values. Changing a token changes every place it's used — instantly consistent.
+
+## Naming Convention
+
+Three levels: **category.semantic.variant**
+
+- `color.primary.default` — not `#3B82F6`
+- `spacing.md` — not `16px`
+- `border.radius.sm` — not `4px`
+
+Category = what kind of value. Semantic = what it's for. Variant = which version.
+
+---
+
+## Color Tokens
+
+### Semantic Color Groups
+
+Every color token is named for its PURPOSE, not its hue.
+
+**Brand**
+```
+color.brand.primary.default     — primary actions, key CTAs
+color.brand.primary.hover       — primary action hover state
+color.brand.primary.active      — primary action pressed state
+color.brand.primary.disabled    — primary action when inactive
+color.brand.secondary.default   — secondary actions
+color.brand.secondary.hover
+color.brand.secondary.active
+```
+
+**Feedback**
+```
+color.feedback.error.default    — error backgrounds, icons
+color.feedback.error.text       — error message text
+color.feedback.error.border     — error input borders
+color.feedback.success.default  — success backgrounds, icons
+color.feedback.success.text     — success message text
+color.feedback.warning.default  — warning backgrounds, icons
+color.feedback.warning.text     — warning message text
+color.feedback.info.default     — info backgrounds, icons
+color.feedback.info.text        — info message text
+```
+
+**Neutral**
+```
+color.neutral.0                 — pure white (page background)
+color.neutral.50                — lightest gray (card backgrounds)
+color.neutral.100               — light gray (hover backgrounds)
+color.neutral.200               — borders, dividers
+color.neutral.300               — placeholder text, disabled borders
+color.neutral.400               — placeholder text
+color.neutral.500               — secondary text
+color.neutral.600               — body text
+color.neutral.700               — headings
+color.neutral.800               — high-emphasis text
+color.neutral.900               — maximum contrast text
+```
+
+**Surface**
+```
+color.surface.page              — page/app background
+color.surface.card              — card, panel backgrounds
+color.surface.overlay           — modal/drawer backdrop
+color.surface.elevated          — dropdown, tooltip backgrounds
+```
+
+**Text**
+```
+color.text.primary              — main body text
+color.text.secondary            — supporting text, labels
+color.text.disabled             — disabled text
+color.text.inverse              — text on dark backgrounds
+color.text.link                 — link text (default)
+color.text.link.hover           — link text on hover
+```
+
+### Color Scale Rule
+
+Pick ONE base hue per semantic group. Generate the full scale from it using consistent lightness steps. Do not mix ad-hoc colors.
+
+---
+
+## Spacing Tokens
+
+A consistent scale. Every margin, padding, gap uses a token from this scale. Nothing else.
+
+```
+spacing.xs    —  4px   (tight internal padding)
+spacing.sm    —  8px   (compact gaps)
+spacing.md    — 16px   (standard gaps, default padding)
+spacing.lg    — 24px   (section internal spacing)
+spacing.xl    — 32px   (between sections)
+spacing.2xl   — 48px   (major section breaks)
+spacing.3xl   — 64px   (page-level spacing)
+spacing.4xl   — 96px   (hero/banner spacing)
+```
+
+**Rule:** Each step is roughly 1.5× the previous. Never invent a value between steps. If nothing fits, use the closest step.
+
+---
+
+## Border Tokens
+
+**Radius**
+```
+border.radius.none    —  0px   (tables, full-bleed)
+border.radius.sm      —  4px   (inputs, small elements)
+border.radius.md      —  8px   (cards, buttons)
+border.radius.lg      — 12px   (modals, large panels)
+border.radius.xl      — 16px   (feature cards)
+border.radius.full    — 999px  (pills, avatars)
+```
+
+**Width**
+```
+border.width.thin     — 1px
+border.width.medium   — 2px   (focus rings, active borders)
+border.width.thick    — 3px   (accents, progress bars)
+```
+
+**Color** — use neutral scale for borders:
+```
+border.color.default  — color.neutral.200  (resting borders)
+border.color.hover    — color.neutral.300  (hovered borders)
+border.color.focus    — color.brand.primary.default  (focused inputs)
+border.color.error    — color.feedback.error.border
+```
+
+---
+
+## Elevation Tokens
+
+Controls depth perception via shadow. Each level implies a specific use case.
+
+```
+elevation.0   — no shadow      (flat, inline elements)
+elevation.1   — subtle shadow  (cards at rest)
+elevation.2   — soft shadow    (cards on hover, dropdowns)
+elevation.3   — medium shadow  (popovers, tooltips)
+elevation.4   — strong shadow  (modals, drawers)
+elevation.5   — heavy shadow   (full-screen overlays)
+```
+
+**Rule:** Never skip levels. A card goes 0→1 on hover, not 0→3.
+
+---
+
+## Motion Tokens
+
+Controls animation timing and easing for consistency.
+
+**Duration**
+```
+motion.duration.fast    — 100ms  (micro-interactions: button press, toggle)
+motion.duration.base    — 200ms  (standard transitions: hover, focus)
+motion.duration.slow    — 300ms  (larger transitions: modal open, panel slide)
+motion.duration.slower  — 500ms  (complex animations: page transitions)
+```
+
+**Easing**
+```
+motion.easing.default   — ease-out       (most transitions)
+motion.easing.enter     — ease-out       (elements appearing)
+motion.easing.exit      — ease-in        (elements disappearing)
+motion.easing.spring    — cubic-bezier   (playful, bouncy — use sparingly)
+```
+
+---
+
+## Project Setup Template
+
+Populate this into `/docs/ui-design/design-system.md` when starting a project. Replace every `[VALUE]` with your project's actual value.
+
+```markdown
+# Project Design System
+
+## Tokens
+
+### Colors
+| Token | Value | Usage |
+|-------|-------|-------|
+| color.brand.primary.default | [VALUE] | Primary CTAs |
+| color.brand.primary.hover | [VALUE] | Primary CTA hover |
+| color.brand.secondary.default | [VALUE] | Secondary actions |
+| color.feedback.error.default | [VALUE] | Error states |
+| color.feedback.success.default | [VALUE] | Success states |
+| color.feedback.warning.default | [VALUE] | Warning states |
+| color.text.primary | [VALUE] | Body text |
+| color.text.secondary | [VALUE] | Supporting text |
+| color.surface.page | [VALUE] | Page background |
+| color.surface.card | [VALUE] | Card background |
+
+### Spacing
+[Use the standard spacing scale from design-tokens.md unless project requires deviation]
+
+### Borders
+[Use standard border tokens unless project requires deviation]
+
+### Elevation
+[Use standard elevation tokens unless project requires deviation]
+
+### Motion
+[Use standard motion tokens unless project requires deviation]
+```

package/ui-design-system/references/layout.md

@@ -0,0 +1,136 @@
+# Layout
+
+## Grid System
+
+All page layouts use a 12-column grid. Columns and gutters use spacing tokens.
+
+```
+| col | col | col | col | col | col | col | col | col | col | col | col |
+  ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^   ^^^
+  gutter between every column = spacing.md (16px)
+  page margin (left and right) = spacing.xl (32px)
+```
+
+### Column Spans
+
+Common layouts expressed in column counts:
+
+| Layout | Columns | Use case |
+|--------|---------|----------|
+| Full width | 12 | Hero, banner, full-width table |
+| Main + sidebar | 8 + 4 | Content page with navigation or details |
+| Main + narrow sidebar | 9 + 3 | Content page with compact sidebar |
+| Two equal | 6 + 6 | Comparison, side-by-side cards |
+| Three equal | 4 + 4 + 4 | Feature cards, stat cards |
+| Four equal | 3 + 3 + 3 + 3 | Product grid, icon grid |
+| Centered content | 8 (centered) | Forms, articles, focused reading |
+
+### Nesting
+
+Grids can nest. A 6-column section can contain its own 12-column sub-grid. The inner grid's columns are proportional to the parent's width.
+
+---
+
+## Responsive Breakpoints
+
+Design mobile-first. Start with the smallest screen, add complexity at each breakpoint.
+
+```
+xs    —    0px–599px    — single column, stacked layout
+sm    —  600px–899px    — two columns available
+md    —  900px–1199px   — three columns available, sidebar layouts
+lg    — 1200px–1535px   — full layout, all columns active
+xl    — 1536px+         — max-width container centered, no further expansion
+```
+
+### Responsive Rules
+
+- **Stack on xs.** Everything is single column. No side-by-side layouts below 600px.
+- **Max-width container.** At xl and above, content stops expanding. Center the container with auto margins.
+- **Touch targets.** On xs and sm, all interactive elements are at least 44×44px.
+- **Typography scales down.** Heading sizes reduce at smaller breakpoints. See `references/typography.md`.
+
+---
+
+## Page Structure
+
+Every page follows this structure. Sections use spacing tokens for vertical rhythm.
+
+```
+┌─────────────────────────────────────┐
+│  Top Navigation Bar                 │  ← fixed or sticky, full-width
+├─────────────────────────────────────┤
+│  Page Header                        │  ← title, subtitle, primary action
+│  spacing.xl below                   │
+├─────────────────────────────────────┤
+│  Content Area                       │  ← grid-based layout
+│                                     │
+│  spacing.xl between major sections  │
+│  spacing.lg between items           │
+│                                     │
+├─────────────────────────────────────┤
+│  Footer (if applicable)             │  ← full-width
+└─────────────────────────────────────┘
+```
+
+### Page Header Patterns
+
+**Simple header:**
+```
+[Page Title]
+[Subtitle or description — optional]                    [Primary Action Button]
+```
+
+**Header with tabs:**
+```
+[Page Title]
+[Tab 1] [Tab 2] [Tab 3]                                [Primary Action Button]
+```
+
+**Header with breadcrumb:**
+```
+[Home] > [Section] > [Current Page]
+[Page Title]                                            [Primary Action Button]
+```
+
+---
+
+## Spacing Rules
+
+### Vertical Spacing (between elements)
+
+| Relationship | Token |
+|---|---|
+| Items in a list or form | spacing.md (16px) |
+| Related groups (label + input) | spacing.xs (4px) |
+| Sections within a card | spacing.lg (24px) |
+| Cards or major blocks | spacing.xl (32px) |
+| Page sections | spacing.2xl (48px) |
+
+### Horizontal Spacing
+
+| Relationship | Token |
+|---|---|
+| Icon to label | spacing.xs (4px) |
+| Items in a toolbar or button group | spacing.sm (8px) |
+| Columns in a form (label → input) | spacing.md (16px) |
+| Card internal padding | spacing.lg (24px) |
+
+### Card Padding
+
+All cards use uniform internal padding:
+- Compact card: `spacing.md` (16px) all sides
+- Standard card: `spacing.lg` (24px) all sides
+- Spacious card: `spacing.xl` (32px) all sides
+
+Pick one size per card type and use it consistently across the product.
+
+---
+
+## Layout Anti-Patterns
+
+- **Pixel-perfect alignment obsession.** Use the grid and spacing tokens. If something doesn't snap to the grid, adjust the design, not the code.
+- **Inconsistent card padding.** Every card of the same type uses the same padding. Period.
+- **Ignoring empty states.** Every list or data view needs a designed empty state. It's not an afterthought — it's the first thing new users see.
+- **Horizontal scrolling on mobile.** If content overflows on xs, it's a layout failure. Stack, truncate, or simplify.
+- **Nesting too deep.** If you're nesting grids more than two levels, the layout is too complex. Break it into separate screens or use progressive disclosure.