@schilling.mark.a/software-methodology 1.0.0

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

@@ -0,0 +1,114 @@
+# Typography
+
+## Type Scale
+
+A fixed scale. Every text element in the product uses exactly one of these sizes. No exceptions.
+
+| Token | Size | Line Height | Weight | Use |
+|---|---|---|---|---|
+| type.display | 36px | 1.2 | 700 | Page hero, landing headlines |
+| type.h1 | 30px | 1.3 | 700 | Page title |
+| type.h2 | 24px | 1.3 | 600 | Section heading |
+| type.h3 | 20px | 1.4 | 600 | Subsection heading |
+| type.h4 | 18px | 1.4 | 600 | Card title, group heading |
+| type.body.lg | 18px | 1.6 | 400 | Lead paragraph, introductory text |
+| type.body.md | 16px | 1.6 | 400 | Standard body text (default) |
+| type.body.sm | 14px | 1.5 | 400 | Secondary text, captions, helper text |
+| type.label | 14px | 1.4 | 500 | Form labels, column headers |
+| type.caption | 12px | 1.4 | 400 | Timestamps, metadata, fine print |
+| type.overline | 12px | 1.4 | 600 | Category labels, tags (uppercase) |
+| type.mono | 14px | 1.5 | 400 | Code, IDs, technical strings |
+
+## Font Family
+
+```
+type.family.sans    — system UI font stack (default for all text)
+type.family.mono    — monospace stack (code, IDs only)
+```
+
+Never use a serif font unless the product explicitly requires editorial content.
+
+---
+
+## Heading Hierarchy Rules
+
+- **One h1 per page.** Always. It is the page title.
+- **h2 before h3.** Never skip levels. No h3 without a parent h2.
+- **Headings are structural, not decorative.** Don't use a heading size just because you want bigger text. Use `type.body.lg` or bold body text instead.
+- **Headings use ubiquitous language.** They are the first thing users scan. Make them match the domain vocabulary.
+
+---
+
+## Text Color Rules
+
+| Context | Token |
+|---|---|
+| Headings (h1–h4) | color.text.primary |
+| Body text | color.text.primary |
+| Secondary / supporting text | color.text.secondary |
+| Placeholder text | color.neutral.400 |
+| Disabled text | color.text.disabled |
+| Links | color.text.link |
+| Links on hover | color.text.link.hover |
+| Error messages | color.feedback.error.text |
+| Success messages | color.feedback.success.text |
+| Warning messages | color.feedback.warning.text |
+| Text on dark backgrounds | color.text.inverse |
+
+---
+
+## Responsive Scaling
+
+Heading sizes reduce at smaller breakpoints. Body text stays constant.
+
+| Token | xs–sm | md | lg+ |
+|---|---|---|---|
+| type.display | 28px | 32px | 36px |
+| type.h1 | 24px | 28px | 30px |
+| type.h2 | 20px | 22px | 24px |
+| type.h3 | 18px | 19px | 20px |
+| type.h4 | 16px | 17px | 18px |
+| type.body.* | no change | no change | no change |
+
+---
+
+## Text Alignment
+
+- **Left-align by default.** Always. For all languages that read left-to-right.
+- **Center only for:** short headlines in hero sections, empty state messages, modal titles.
+- **Never right-align** body text or headings. Right-align only numbers in table columns for readability.
+
+---
+
+## Truncation
+
+When text overflows its container:
+- **Single line:** ellipsis (`…`) at the end. CSS `text-overflow: ellipsis`.
+- **Multi-line (2–3 lines):** ellipsis at the end of the last visible line. CSS `-webkit-line-clamp`.
+- **Never hide text silently.** If text is truncated, the full text must be available on hover (tooltip) or on interaction (expand).
+
+---
+
+## Lists
+
+**Unordered lists:**
+- Bullet: `spacing.sm` (8px) left indent
+- Item spacing: `spacing.sm` (8px) between items
+- Use for items with no inherent order
+
+**Ordered lists:**
+- Number: `spacing.sm` (8px) left indent
+- Item spacing: `spacing.sm` (8px) between items
+- Use only when sequence matters
+
+**No nesting deeper than two levels.** If you need three levels, restructure the content.
+
+---
+
+## Anti-Patterns
+
+- **All caps for emphasis.** Use font-weight instead. All caps is reserved for `type.overline` only.
+- **More than two font weights on one screen.** 400 (regular) and 600 (semi-bold) cover almost everything. Add 700 (bold) only for display/h1.
+- **Justified text.** Creates uneven word spacing. Left-align instead.
+- **Line length over 75 characters.** Long lines are hard to read. Constrain text containers. Centered content columns (8 of 12 grid columns) naturally prevent this.
+- **Font size below 12px.** Anything smaller is unreadable on most screens, especially mobile. `type.caption` at 12px is the floor.

package/ui-design-workflow/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ui-design-workflow
+description: UI design workflow for translating Gherkin scenarios into concrete interface designs before implementation. Use when a feature has acceptance scenarios with user-facing UI, when planning what screens or components a feature needs, when the user says "design the UI", "what does this look like", or "plan the interface". Reads feature files and story map tasks. Produces screen-flow documents and component specs that acceptance tests verify against. Works alongside bdd-specification and atdd-workflow skills.
+---
+
+# UI Design Workflow
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Overview
+
+Bridges the gap between Gherkin scenarios and implementation. Takes the "what the user does and sees" from feature files and translates it into concrete screen flows, component decisions, and interaction specs. The output becomes the target that acceptance tests verify.
+
+## Before Starting — Read Context
+
+1. `/features/[domain]/[feature].feature` — the scenarios being designed for
+2. `/docs/story-map/user-tasks/[task-id].md` — task context and acceptance criteria
+3. `/docs/value-proposition-canvas.md` — user goals and pain points
+4. `/docs/ui-design/design-system.md` — tokens, components, layout rules (project-specific, populated from ui-design-system skill)
+5. `/docs/ui-design/screen-flows/` — existing screen flows for consistency
+
+## Workflow Decision
+
+**Feature has UI-facing scenarios?** → Follow "Design Workflow" below
+**Feature is API-only or background processing?** → Skip this skill entirely
+**Unsure?** → Check the Gherkin scenarios. If any Then step says "I should see", "I should be able to", or references a screen or page, it has UI.
+
+## Design Workflow
+
+### Step 1: Extract UI Requirements from Scenarios
+
+Read each Gherkin scenario and identify:
+- **Screens** — what pages or views are needed
+- **Entry points** — how the user gets to each screen
+- **Data displayed** — what information appears on each screen
+- **Actions available** — what the user can do on each screen
+- **State changes** — how the screen changes in response to actions
+- **Error states** — what the user sees when something fails
+
+See `references/scenario-to-ui.md` for the extraction process and mapping patterns.
+
+### Step 2: Design Screen Flows
+
+Map the extracted requirements into a connected flow of screens. Each screen flow document covers one feature's worth of screens.
+
+See `references/screen-flows.md` for structure, notation, and file format.
+
+Create: `/docs/ui-design/screen-flows/[feature-name].md`
+
+### Step 3: Select Components
+
+For each screen, identify which components from the design system are needed and which need to be created new.
+
+See `references/component-selection.md` for decision guidance — when to use existing components, when to create new ones, and how to spec a new component.
+
+### Step 4: Define Acceptance Targets
+
+Translate design decisions into observable, testable assertions. These become the "Then" steps that acceptance tests verify.
+
+See `references/acceptance-targets.md` for how to express design decisions as testable outcomes.
+
+### Step 5: Update Feature File
+
+If the design process revealed that scenarios need refinement (missing states, ambiguous actions), update the feature file in collaboration with bdd-specification skill before handing off to atdd-workflow.
+
+## File Structure
+
+```
+docs/ui-design/
+├── design-system.md                 ← Project's design system (from ui-design-system skill)
+├── screen-flows/
+│   ├── [feature-name].md           ← Screen flow for one feature
+│   └── [feature-name].md
+└── components/
+    └── [component-name].md         ← Spec for a new component (if needed)
+```
+
+## Integration
+
+```
+bdd-specification  →  writes Gherkin scenarios (Given/When/Then)
+    ↓
+ui-design-workflow (this skill)  →  translates scenarios into screen flows and component specs
+    ↓
+atdd-workflow  →  implements with RED-GREEN-REFACTOR
+    ↓ (acceptance tests verify against)
+ui-design-workflow  →  screen flows and acceptance targets define what "passing" looks like
+```

package/ui-design-workflow/references/acceptance-targets.md

@@ -0,0 +1,144 @@
+# Acceptance Targets
+
+## What Are Acceptance Targets?
+
+Design decisions translated into observable outcomes that acceptance tests can verify. Every significant design decision must have at least one acceptance target — otherwise it's untestable and will drift.
+
+## What Is Testable vs What Is Not
+
+**Testable — acceptance tests can verify:**
+- Element is present on the screen
+- Element contains specific text or data
+- Element is in a specific state (visible, hidden, disabled, focused)
+- Action produces a specific result (navigation, state change, data update)
+- Error message appears in response to invalid input
+- Layout relationship (element A appears before element B)
+- Accessible properties (role, label, keyboard behavior)
+
+**Not testable by acceptance tests — leave to visual review:**
+- Exact color values (unless tied to a semantic meaning like error=red)
+- Precise spacing or margins
+- Font weight or style
+- Animation timing or easing
+- Aesthetic judgment calls
+
+## Mapping Design Decisions to Targets
+
+For each screen in the flow, identify the design decisions that matter and express them as acceptance targets.
+
+### Pattern 1: Element Presence
+
+**Design decision:** "The invoice detail page shows the invoice number at the top"
+**Acceptance target:**
+```
+Then I should see the invoice number displayed
+```
+**Test verifies:** Element with invoice number text exists on the page
+
+### Pattern 2: Element State
+
+**Design decision:** "The Save button is disabled until all required fields are filled"
+**Acceptance target:**
+```
+Then the Save button should be disabled
+When I fill in all required fields
+Then the Save button should be enabled
+```
+**Test verifies:** Button's disabled attribute changes based on form state
+
+### Pattern 3: Conditional Visibility
+
+**Design decision:** "The discount field only appears when the customer has a discount agreement"
+**Acceptance target:**
+```
+Given customer "ACME Corp" has a discount agreement
+Then I should see the discount field
+
+Given customer "New Corp" has no discount agreement
+Then I should not see the discount field
+```
+**Test verifies:** Element presence/absence based on data condition
+
+### Pattern 4: Navigation
+
+**Design decision:** "Clicking an invoice row navigates to the invoice detail page"
+**Acceptance target:**
+```
+When I click on invoice "INV-2024-001"
+Then I should be on the invoice detail page
+And I should see invoice number INV-2024-001
+```
+**Test verifies:** Page transition and correct data load
+
+### Pattern 5: Error Display
+
+**Design decision:** "Validation errors appear inline below the field that failed"
+**Acceptance target:**
+```
+When I enter an invalid amount
+And I attempt to save
+Then I should see error "Amount must be positive" below the amount field
+```
+**Test verifies:** Error message presence and location relative to the field
+
+### Pattern 6: Data Formatting
+
+**Design decision:** "Monetary amounts display with currency symbol and two decimal places"
+**Acceptance target:**
+```
+Then I should see total displayed as "$1,500.00"
+```
+**Test verifies:** Exact formatted string, not raw number
+
+### Pattern 7: Empty State
+
+**Design decision:** "When no invoices exist, show a message prompting the user to create one"
+**Acceptance target:**
+```
+Given no invoices exist
+When I view the invoice list
+Then I should see "No invoices yet. Create your first invoice."
+And I should see a "Create Invoice" button
+```
+**Test verifies:** Empty state message and call-to-action presence
+
+### Pattern 8: Loading State
+
+**Design decision:** "While data is loading, show a loading indicator and disable actions"
+**Acceptance target:**
+```
+When the page is loading
+Then I should see a loading indicator
+And all action buttons should be disabled
+```
+**Test verifies:** Loading state renders correctly (may require mocked slow response in test)
+
+## Acceptance Target Document
+
+At the end of each screen flow, produce a consolidated list:
+
+```markdown
+## Acceptance Targets: [Feature Name]
+
+### [Screen Name]
+- [ ] [Target 1 — element presence]
+- [ ] [Target 2 — state condition]
+- [ ] [Target 3 — navigation]
+- [ ] [Target 4 — error display]
+- [ ] [Target 5 — empty state]
+
+### [Screen Name]
+- [ ] [Target 1]
+- [ ] [Target 2]
+```
+
+These targets feed directly into the acceptance test assertions during the RED phase of atdd-workflow. Each checkbox becomes a test case.
+
+## Traceability
+
+Every acceptance target traces back to:
+- A design decision in the screen flow
+- A scenario in the feature file
+- A Then step in Gherkin
+
+If a target has no corresponding Then step, either add one to the feature file or remove the target — every testable design decision should be covered by a scenario.

package/ui-design-workflow/references/component-selection.md

@@ -0,0 +1,108 @@
+# Component Selection
+
+## Decision: Use Existing or Create New?
+
+For each UI element in a screen flow, run this decision tree:
+
+### Does a component already exist in the design system that does this?
+**Yes** → Use it. Do not create a variant unless the existing component genuinely cannot accommodate the need.
+**No** → Continue to next question.
+
+### Can an existing component be composed to achieve this?
+**Yes** → Compose. Example: a labeled input is just a Label + Input + HelperText arranged vertically. No new component needed.
+**No** → Continue to next question.
+
+### Is this element likely to appear in more than one screen or feature?
+**Yes** → Create a new reusable component. Spec it in `/docs/ui-design/components/[name].md`
+**No** → Implement inline in the screen. It's a one-off layout detail, not a component.
+
+## When Existing Components Need Modification
+
+If an existing component almost works but needs a small addition, prefer:
+
+1. **Props first** — can a new prop configure the existing component? (e.g., `size="compact"`, `variant="inline"`)
+2. **Composition second** — can you wrap the component with additional elements?
+3. **New variant last** — only if the behavior is fundamentally different, not just visually different
+
+**Never fork a component** to create a slightly different version. Two components that drift apart are harder to maintain than one flexible component.
+
+## Specifying a New Component
+
+When a new component is needed, create: `/docs/ui-design/components/[component-name].md`
+
+```markdown
+# Component: [Name]
+
+**First used in:** [feature name], [screen name]
+**Design system token group:** [which token group it belongs to — e.g., form, feedback, navigation]
+
+## Purpose
+[One sentence: what this component does for the user]
+
+## When to Use
+- [Situation where this component is appropriate]
+- [Another situation]
+
+## When NOT to Use
+- [Situation where a different component is better]
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| [name] | [type] | Yes/No | [value] | [what it does] |
+
+## States
+
+| State | Description | Visual indication |
+|-------|-------------|-------------------|
+| Default | [normal state] | [how it looks] |
+| Hover | [mouse over] | [how it looks] |
+| Focus | [keyboard focus] | [how it looks] |
+| Disabled | [not interactive] | [how it looks] |
+| Error | [invalid state] | [how it looks] |
+| Loading | [waiting for data] | [how it looks] |
+
+## Variants
+- **[Variant name]:** [when to use this variant, how it differs]
+
+## Accessibility
+- **Role:** [ARIA role]
+- **Keyboard:** [how keyboard navigation works]
+- **Screen reader:** [what gets announced]
+- **Color contrast:** [meets WCAG AA minimum]
+
+## Usage Example
+```
+[Show the component in context — which props, which state, 
+placed within a parent layout]
+```
+
+## Do Not
+- [Anti-pattern specific to this component]
+- [Another anti-pattern]
+```
+
+## Component Categories
+
+Organize components into these categories. New components should be placed in the correct category:
+
+**Form** — inputs, selects, checkboxes, radio buttons, text areas, date pickers
+**Feedback** — alerts, toasts, error messages, validation messages, loading indicators, progress bars
+**Navigation** — nav bars, breadcrumbs, tabs, pagination, back buttons, sidebars
+**Layout** — cards, panels, modals, drawers, accordions, grids
+**Display** — tables, lists, badges, avatars, icons, chips/tags
+**Action** — buttons, icon buttons, menus, dropdowns, context menus
+
+## Reuse Rules
+
+- A component used in 1 place is a layout detail
+- A component used in 2+ places is a candidate for the design system
+- A component used in 3+ places is a design system component — spec it formally
+- All design system components must have documented props, states, and accessibility
+
+## Naming Conventions
+
+- PascalCase: `InvoiceStatusBadge`, not `invoice-status-badge`
+- Name after what it IS, not where it's used: `StatusBadge`, not `InvoicePageBadge`
+- If a component is a variant of another, use a prop: `Badge variant="status"`, not a new `StatusBadge` component

package/ui-design-workflow/references/scenario-to-ui.md

@@ -0,0 +1,151 @@
+# Extracting UI Requirements from Gherkin Scenarios
+
+## Mapping Process
+
+Read each scenario and extract six categories of UI requirement. Not every scenario produces all six — extract only what's present.
+
+### 1. Screens
+
+Identify every distinct view or page the scenario touches.
+
+**Signals in Gherkin:**
+- "Given I am on the [X] page"
+- "When I navigate to [X]"
+- "Then I should see the [X] screen"
+
+**Example:**
+```gherkin
+Scenario: Create invoice
+  Given I am on the invoice list page
+  When I click create
+  Then I should see the new invoice form
+```
+→ Screens: Invoice List, New Invoice Form
+
+### 2. Entry Points
+
+How does the user get to each screen? Every screen must have at least one entry point.
+
+**Signals in Gherkin:**
+- "When I click [X]"
+- "When I navigate to [X]"
+- "When I select [X] from [Y]"
+
+**Example:**
+```
+Invoice List → [Create button] → New Invoice Form
+Invoice List → [Invoice row] → Invoice Detail
+```
+
+### 3. Data Displayed
+
+What information must appear on each screen for the scenario to work?
+
+**Signals in Gherkin:**
+- "Then I should see [specific data]"
+- "Then I should see [entity] with [attributes]"
+
+**Example:**
+```gherkin
+Then I should see invoice number INV-2024-001
+And I should see customer "ACME Corp"
+And I should see total $1,500.00
+```
+→ Invoice Detail must display: invoice number, customer name, total
+
+### 4. Actions Available
+
+What can the user do on each screen? Actions become buttons, links, or interactive controls.
+
+**Signals in Gherkin:**
+- "When I [verb] the [noun]"
+- "When I click [X]"
+- "When I enter [value] into [field]"
+- "When I select [option]"
+
+**Example:**
+```
+New Invoice Form actions:
+- Enter customer name (text input)
+- Add line item (button)
+- Enter line item description (text input)
+- Enter line item amount (number input)
+- Save (button)
+- Cancel (button)
+```
+
+### 5. State Changes
+
+How does the screen change in response to an action? This drives component state and conditional rendering.
+
+**Signals in Gherkin:**
+- "Then I should see [X] change to [Y]"
+- "Then [element] should [appear/disappear/update]"
+- "Then I should be redirected to [screen]"
+
+**Example:**
+```
+After save:
+- Form disappears
+- User is redirected to Invoice Detail
+- Invoice Detail shows the new invoice data
+
+After add line item:
+- New empty line item row appears in the form
+- Total updates to include new line item
+```
+
+### 6. Error States
+
+What does the user see when something goes wrong?
+
+**Signals in Gherkin:**
+- "Then I should see error [message]"
+- "Then I should see validation [message]"
+- "And the [entity] should not be saved"
+
+**Example:**
+```
+New Invoice Form errors:
+- Customer not found: inline error below customer field
+- Amount is negative: inline error below amount field
+- Save fails: banner error at top of form
+```
+
+## Extraction Template
+
+For each feature, produce this summary before designing screen flows:
+
+```markdown
+## UI Requirements: [Feature Name]
+
+### Screens
+- [Screen 1]: [purpose]
+- [Screen 2]: [purpose]
+
+### Entry Points
+- [Screen A] → [action] → [Screen B]
+
+### Data Displayed
+- [Screen 1]: [list of data elements]
+- [Screen 2]: [list of data elements]
+
+### Actions
+- [Screen 1]: [list of actions with control types]
+- [Screen 2]: [list of actions with control types]
+
+### State Changes
+- [Action] → [what changes and where]
+
+### Error States
+- [Error condition] → [what user sees and where]
+```
+
+## Common Gaps
+
+If extraction reveals any of these, the feature file needs updating before design proceeds:
+
+- A screen with no entry point — how does the user get there?
+- An action with no outcome — what happens when the user does this?
+- Data displayed but never explained how it gets there — where does this data come from?
+- An error mentioned but the recovery path is unclear — what does the user do after seeing the error?