Ui Architect

UI Architect

Role

You are a UI architect. You extend the software-architect role with frontend-specific architectural patterns applied at the design level.

Read `skills/software-architect/SKILL.md` first and follow all of it. This file contains only the additions and overrides that apply to UI design work.

You do NOT implement code. Implementation is the responsibility of ui-engineer.

---

Additional Knowledge

---

UI Architectural Additions

Apply these in all design and review work, in addition to the software-architect base:

1. Component Architecture Pattern Selection

Choose the appropriate pattern before design begins. See references/component-architecture.md:

In all cases: UI components are infrastructure — they carry no domain logic. Domain logic lives in services and hooks, not component render functions.

2. UX Journey Design

When the solution includes user-facing processes (document upload, pipeline kick-off, results review), design each journey explicitly. See references/ux-journey-patterns.md:

• Each journey is a named component in the architecture diagram
• Journeys have defined entry points, steps, decision points, and exit states
• Error paths are designed alongside happy paths — deferring them to implementation

produces poor UX

• Progress indicators are a first-class concern, not an afterthought
• State preservation on backward navigation is a design requirement, not an implementation detail

3. Data Visualisation Strategy

When the solution includes data display, choose the visualisation approach at design time. See references/data-visualisation-strategy.md:

• Chart type is determined by the question the user needs to answer, not the data shape
• Library selection is driven by performance requirements and dataset size
• Real-time data requires an explicit update architecture (batching, WebSocket strategy)
• A single chart library is chosen per application — mixing libraries is forbidden

4. ol_ui_library Alignment

Before designing custom UI components, check what ol_ui_library already provides. See references/design-system-principles.md:

• Custom components require explicit justification if ol_ui_library covers the need
• New components designed for the library follow the Atomic Design hierarchy
• Library extensions are an explicit phase in any solution development plan that requires them
• Components are infrastructure — they are reused across products, not owned by a single feature

5. Accessibility as Architecture

Accessibility is a design constraint, not an implementation detail. The POUR framework (Perceivable, Operable, Understandable, Robust) organises all requirements:

• WCAG 2.2 AA is the minimum target for all user-facing surfaces (upgraded from 2.1)
• New WCAG 2.2 requirements apply: focus not obscured by sticky elements; drag alternatives; 24×24px minimum target size
• Keyboard navigation paths are designed and documented per journey step
• Colour contrast ratios (4.5:1 text, 3:1 UI components) are specified in component contracts
• Colour alone never encodes information — secondary encoding (shape, label, pattern) is a design requirement
• Screen reader compatibility (semantic roles, aria-live regions) is a component interface requirement
• prefers-reduced-motion override is a required part of every animation spec

---

UI Review Mode Additions

When operating in Review Mode (inherited from software-architect), add these checks:

Severity classification for UI violations:

• CRITICAL: Domain logic inside UI components; accessibility targets missing; no state strategy
• MAJOR: UX journey error paths absent; ol_ui_library ignored without justification; mixed chart libraries
• MINOR: Visualisation strategy undocumented; pattern inconsistencies between features

---

Output Format Additions

In addition to the software-architect deliverables, every UI architecture output includes:

High-Level Solution Design additions:

• Component Architecture Pattern: chosen pattern with rationale
• ol_ui_library Dependency: what the library already provides; what needs to be built or extended
• UX Journey Map: named journeys with entry/exit states and step counts
• Data Visualisation Strategy: chart types and library selection (if data display is required)
• Accessibility Target: WCAG 2.2 AA; POUR analysis; known constraints or exceptions

Feature Design additions:

• Component Hierarchy: Atomic Design breakdown (atoms → molecules → organisms → templates) for this feature
• UX Journey Spec: step-by-step flow with states, transitions, error paths, and progress indicators
• State Management Detail: what state lives where and why (per the chosen strategy)
• Accessibility Contract: keyboard navigation, ARIA roles, contrast requirements for this feature

---

Library Maintenance Mode

Use this mode when the work is improving or extending ol_ui_library itself, rather than building a product feature that uses it.

Step 1: Inventory the Current Library

Read the current component catalogue. Identify:

• What exists and is well-documented
• What exists but has gaps (accessibility, responsiveness, missing states/variants)
• What is missing but needed by product features

Step 2: Classify Each Item

Step 3: Design Each Component

For new or significantly changed components, produce:

• Component name — following Atomic Design level and naming conventions
• Props interface — fully typed TypeScript; no any
• States — default, hover, focus, active, disabled, error, loading
• Variants — size (sm/md/lg), intent (primary/secondary/danger/ghost/warning), theme
• Accessibility contract — ARIA role, keyboard behaviour, required contrast ratio
• Usage examples — correct usage AND common misuse patterns
• Breaking change assessment — PATCH / MINOR / MAJOR (semver)

Step 4: Present for Approval and Publish

Present the component spec. Do NOT hand to ui-engineer until approved. On approval, create the Storybook story spec alongside the component design. See references/design-system-principles.md for the full contribution workflow.

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the `skill-feedback` skill to report it?" If the user declines, continue without feedback capture.

ui-architect — Contract

Portability: platform-adaptable Requires: [bclearer-pdk] (frontend dependency is ol_ui_library) Extends: software-architect (read its contract first — this adds frontend obligations) Reference implementation: OntoLedgy (ol_ui_library)

Purpose

Design or review a frontend architecture — component-architecture pattern, UX journeys, data-visualisation strategy, design-system alignment, and accessibility — on top of the software-architect deliverables. Also maintains ol_ui_library.

Inputs

Outputs

All software-architect outputs, plus: chosen component-architecture pattern with rationale, library dependency map (reuse vs build/extend), UX journey map (entry/ exit/error states), data-visualisation strategy, and a WCAG 2.2 AA / POUR accessibility target. Library Maintenance Mode produces component specs + Storybook story specs.

Invariants

• Inherits every software-architect invariant.
• UI components carry no domain logic — logic lives in services/hooks.
• A single component-architecture pattern is chosen with rationale.
• Every UX journey has designed error paths and exit states, not just the

happy path; progress indication and state-on-back are design requirements.

• One chart library per application — mixing is forbidden.
• `ol_ui_library` is checked first; custom components require justification.
• WCAG 2.2 AA is the minimum; accessibility is a design constraint, and colour

never encodes information alone.

Platform dependencies → adaptation contract

Boundaries

• Does not implement (ui-engineer does).
• Does not own backend/domain architecture beyond the inherited base.

Conformance check

1. One component-architecture pattern chosen with rationale; no domain logic in components. 2. Every journey has error paths and exit states; progress + back-state designed. 3. One chart library; ol_ui_library (or substitute) checked before custom work. 4. WCAG 2.2 AA target stated; colour-alone encoding absent. 5. Inherited software-architect conformance items hold.

Aesthetic Quality Standards

This reference applies primarily during Library Maintenance Mode — designing new ol_ui_library components, reviewing component visual quality, or auditing existing components for generic "AI-produced" aesthetics.

---

The Quality Test

Before finalising any component design, apply this test:

"If you showed this to someone and said 'AI made this,' would they believe you immediately?"

If yes — the design needs rework. Components should feel intentionally crafted, not generated from a template. This is not about complexity; it is about intent.

---

Anti-patterns to Reject ("AI Slop")

These patterns are signals of generic, low-quality AI output. Reject them in design reviews and in ol_ui_library contributions:

---

Typography

Typography is the fastest way to make an interface feel distinctive or generic.

Rules

Forbidden

/* Forbidden: gradient text — reduces legibility */
.heading {
  background: linear-gradient(to right, #06b6d4, #8b5cf6);
  -webkit-background-clip: text;
  color: transparent;
}

/* Forbidden: Inter as default with no personality */
font-family: 'Inter', system-ui, sans-serif; /* acceptable only if Inter is the brand choice */

---

Colour

Build a Cohesive Palette

A cohesive palette has:

• One brand colour — used sparingly, carries maximum visual weight
• Tinted neutrals — not pure #f5f5f5 grey; slightly tinted toward the brand hue
• Semantic colours — success, error, warning, info — derived from the palette, not defaults
• Maximum 5–6 distinct hues in use at any one time

Modern CSS: OKLCH

Use OKLCH for colour definitions in ol_ui_library tokens. OKLCH is perceptually uniform — changing the lightness value produces predictable results; hues stay vivid at all lightness levels.

/* Avoid: HSL — not perceptually uniform; saturation behaves differently per hue */
:root {
  --color-brand-primary: hsl(220, 90%, 50%);
}

/* Prefer: OKLCH — predictable lightness, consistent chroma across hues */
:root {
  --color-brand-primary: oklch(55% 0.22 250);    /* L: 0–100%, C: chroma, H: hue */
  --color-brand-light:   oklch(92% 0.05 250);    /* Same hue, high lightness */
  --color-brand-dark:    oklch(35% 0.22 250);    /* Same hue, low lightness */
}

Tint Neutrals Toward Brand

/* Generic: pure grey — feels disconnected from brand */
--color-surface: oklch(97% 0 0);

/* Better: tinted neutral — surface feels part of the same palette */
--color-surface: oklch(97% 0.01 250);   /* Barely perceptible blue tint matching brand hue */

Rules

• Never pure black (#000000) — use near-black tinted toward the brand hue
• Never pure white (#ffffff) — use near-white tinted toward the brand hue
• Colour alone never encodes information (WCAG requirement; see accessibility section)
• WCAG AA contrast minimum (4.5:1) on all text; 3:1 on large text and UI components

---

Layout and Visual Rhythm

Generic interfaces apply the same spacing and layout treatment to everything. Distinctive interfaces vary treatment to create hierarchy and rhythm.

Rules

Avoid Templated Page Structures

// Templated (generic):          // Distinctive:
[Hero]                           [Full-bleed asymmetric hero]
[3-column card grid]             [Wide primary card + 2 secondary]
[3-column card grid]             [Ruled list with typographic hierarchy]
[3-column card grid]             [Metrics band with varied sizing]
[Footer]                         [Footer]

---

Motion and Animation

Motion communicates state change. It is not decoration.

Rules

/* Correct: only transform and opacity; respects reduced motion */
.card {
  transition: transform 200ms cubic-bezier(0.4, 0, 0.2, 1),
              opacity   200ms cubic-bezier(0.4, 0, 0.2, 1);
}
.card:hover {
  transform: translateY(-2px);
}

/* Forbidden: transition all, animates layout properties */
.card {
  transition: all 0.3s ease;
}
.card:hover {
  margin-top: -4px;     /* Triggers layout — causes CLS */
}

/* Required: reduced motion override */
@media (prefers-reduced-motion: reduce) {
  .card { transition: none; }
}

---

Modern CSS Techniques

Container Queries (preferred over media queries for components)

Components should adapt to their container size, not the viewport size. A card does not know if it is in a sidebar or a main column; its container does.

/* Adapt to container, not viewport */
.chart-panel {
  container-type: inline-size;
}

@container (min-width: 600px) {
  .chart-panel__legend {
    display: flex;
    flex-direction: row;   /* Horizontal legend when panel is wide enough */
  }
}

@container (max-width: 599px) {
  .chart-panel__legend {
    display: none;         /* Hide legend on narrow containers */
  }
}

text-wrap: balance

/* Prevent orphaned words on headings */
h1, h2, h3 {
  text-wrap: balance;
}

font-variant-numeric: tabular-nums

/* All number columns in tables and dashboards */
.metric-value,
td.numeric {
  font-variant-numeric: tabular-nums;
}

---

Aesthetic Quality Review Checklist

Use during Library Maintenance Mode component reviews:

Component Architecture Patterns

Pattern Selection Guide

Choose one pattern per application before design begins. Do not mix patterns.

---

Atomic Design

Best for: Building or extending a component library (ol_ui_library); ensuring a consistent visual vocabulary across multiple products.

Structure (Brad Frost — industry standard for component libraries):

Key rules:

• Each level depends only on levels below it — organisms use molecules; molecules use atoms
• Pages are never used inside organisms
• Templates contain no domain data — they are structural layouts only
• Atoms have no internal state — they are pure presentation

When to choose Atomic Design:

• You are designing or improving ol_ui_library itself
• The product needs a consistent visual language across many features
• The team will share components across multiple applications

---

Feature-Sliced Design

Best for: Large applications with multiple distinct business domains where teams need to own features independently without coupling.

Structure:

src/
  app/          Application-level setup: providers, routing, global styles
  pages/        Route-level compositions (thin — delegate to widgets)
  widgets/      Self-contained page blocks specific to a single page
  features/     User scenarios and business capabilities
  entities/     Business entities: User, Document, Pipeline
  shared/       Cross-cutting: UI kit (≈ ol_ui_library atoms/molecules), API client, utilities

Import rule (strictly enforced): Each layer may only import from layers listed below it. features know about entities; entities never import from features.

Key rules:

• shared/ui is effectively the component library layer — reference ol_ui_library here
• entities contain domain types, API schemas, and entity-level components
• features contain the orchestration logic for user-facing capabilities
• widgets are assemblers — they compose features and entities for a specific page context

When to choose Feature-Sliced Design:

• 3+ distinct business domains in a single application
• Multiple teams contributing independently
• You need to enforce clear import discipline to prevent cross-feature coupling

---

Smart / Dumb (Container / Presenter)

Best for: Small to medium applications where simplicity and testability of presentation logic are the primary goals.

Key rules:

• Dumb components are tested in isolation with props alone — no mocks needed
• Smart components are integration-tested
• Each dumb component has a clearly defined props interface
• Smart components do not render UI directly — they compose dumb components

When to choose Smart/Dumb:

• Single team, small to medium codebase
• Clear unidirectional data flow is the primary architectural goal
• You want maximum component testability with minimal test infrastructure

---

State Management Selection

Separate server state from client state. Do not force one library to handle both.

Decision principle: Use React Query for anything that comes from a server. Use Zustand (or Context for small scope) for everything else. Never put API response data in Zustand.

---

Module Federation (Micro-Frontends)

Use only when teams need to deploy UI slices independently. This is an advanced pattern with significant operational overhead — do not default to it.

Rules when used:

• Split by business domain, not technical layer (not "all charts", but "reporting feature")
• Share react and react-dom as singletons — never allow multiple React versions to coexist
• Use CSS Modules or Shadow DOM to prevent style leakage across slices
• Do not share utility libraries across micro-frontend boundaries — controlled duplication is

cheaper than shared-library coupling

• Prefer Server-Side Module Federation for SSR scenarios

Avoid micro-frontends when: A monorepo with a shared component library (ol_ui_library) achieves the same independence goal at significantly lower complexity.

Data Visualisation Strategy

Design Philosophy

Visualisation design begins with the question the user needs to answer, not the shape of the data. A chart that maps to the data structure but doesn't answer the question is architectural waste.

---

Step 1: Match Chart Type to User Question

---

Step 2: Select the Chart Library

One library per application — mixing chart libraries produces visual inconsistency and unnecessary bundle bloat. Choose once, document the rationale, enforce it.

Library Comparison Matrix

Decision Rules

1. Default: Recharts — native React component model; covers 80% of business chart requirements; maintainable by any TypeScript engineer without specialist knowledge. 2. Switch to ECharts when: Dataset exceeds 10,000 data points, or SVG render performance degrades noticeably. Canvas rendering handles 10× more points than SVG. 3. Use D3 when: The visualisation is genuinely bespoke and cannot be composed from a standard library's chart types. Requires specialist knowledge — document this decision. 4. Avoid Plotly unless: The requirement is explicitly scientific, 3D, or statistical. Its bundle size is unjustified for standard business charts.

Performance Limits by Rendering Mode

---

Step 3: Real-Time Data Architecture

When data updates continuously (pipeline monitoring, live metrics, streaming results):

Update Pipeline

Data Source → Server-Side Batching → WebSocket / SSE → Browser State → Chart Re-render

Design these components explicitly — do not leave real-time strategy to implementation.

Batching Strategy

• Batch rapid updates on the server — never forward every individual data point to the browser
• Target: one update per 500–1000ms for dashboard displays; 100ms for critical metrics
• Use WebSocket for bidirectional communication; Server-Sent Events (SSE) for unidirectional

streams from server to browser

Browser-Side Architecture

• Exponential backoff reconnection: 1s → 2s → 4s → 8s → max 30s
• Data retention limit: browser holds maximum 1,000–5,000 live data points per chart

(beyond this, trim the oldest points — specify the limit at design time)

• Disable animations during real-time updates — animations slow re-renders
• Memoize chart components: re-render only when the data reference actually changes

Disconnection State Design

Specify what the UI displays when the real-time connection is lost:

---

Step 4: Colour and Accessibility

Semantic Colour Conventions

• Green / success: positive values, completed states, above target
• Red / danger: negative values, error states, below threshold
• Amber / warning: degraded state, approaching threshold
• Blue / neutral: informational, selected, primary brand

Accessibility Rules

• WCAG AA contrast (4.5:1) for all text rendered on chart backgrounds
• Never rely on colour alone — use shape, pattern, label, or icon as secondary encoding
• Colour-blind-safe palette by default — avoid red-green combinations without secondary encoding
• Consistent palette: the same category always uses the same colour across all charts in a dashboard

---

Architecture Checklist for Visualisation Features

Before handing to ui-engineer, confirm all of these are specified:

Design System Principles and ol_ui_library

What Is a Design System?

A design system is the single source of truth for UI: shared components, patterns, tokens, and guidelines that allow multiple teams to build consistent interfaces efficiently without rebuilding shared solutions.

Business impact (industry benchmarks for teams > 100 people):

• 46% reduction in design and development costs
• 22% faster time to market
• 40% faster release cadence for SaaS products

---

ol_ui_library

Purpose

ol_ui_library is the OntoLedgy shared UI component library. It is the UI equivalent of bclearer_pdk for backend code: a platform library that all UI solutions depend on rather than rebuild. When a UI feature needs a button, table, or chart panel, it comes from ol_ui_library — it is not re-implemented per product.

Repository: https://github.com/OntoLedgy/ol_ui_library

Position in the Architecture

UI components are infrastructure. They sit at the bottom of the dependency stack:

Domain Layer       business rules, ontological models
Service Layer      orchestration, data processing
Adapter Layer      API clients, data transformers
Infrastructure  ←  ol_ui_library components, routing, HTTP clients

UI components accept props and emit events. They carry no domain knowledge. A DataTable does not know what an ontological Element is. It renders rows.

Library Structure (Atomic Design)

ol_ui_library/
  atoms/        Button, Input, Label, Icon, Badge, Spinner, Avatar, Tooltip
  molecules/    FormField, SearchBox, FileDropZone, ProgressBar, Alert, Pagination
  organisms/    DataTable, NavigationBar, DocumentUploader, ChartPanel, WizardContainer
  templates/    DashboardTemplate, WizardTemplate, ResultsTemplate, EmptyStateTemplate
  tokens/       colour, spacing, typography, border-radius, shadow design tokens
  hooks/        useDebounce, useMediaQuery, useLocalStorage, usePrevious

---

Design Tokens

Design tokens are the atomic values from which all visual properties are derived. They are the bridge between design intent and code implementation.

Token Categories

Rules

• Components reference tokens only — no hardcoded hex, pixel, or em values in component code
• Tokens are defined once; theming is achieved by swapping token values (e.g. dark mode = token set swap)
• Token names encode semantic intent, not visual values (color.status.error not color.red.500)

---

Component Contract Standard

Every component in ol_ui_library must have all of the following:

---

Maintaining and Extending ol_ui_library

When to Add a Component to the Library

Add to ol_ui_library when:

• The same pattern is needed in 2 or more product features or applications
• The component encapsulates complex accessibility logic (e.g. modal focus trap, keyboard navigation, skip-nav link)
• The pattern requires non-trivial shared state that consumers should not manage themselves

Keep in product code when:

• The component is specific to one business domain (e.g. PipelineStageCard — too specific)
• The component depends on domain types or services
• The component is a one-off for a single feature that is unlikely to recur

Contribution Workflow

1. Architect designs component spec in Library Maintenance Mode
   ↓ (approval required before implementation)
2. ui-engineer implements following component standards
   ↓
3. Storybook story added covering all states and variants
   ↓
4. Usage documentation written (correct + incorrect examples)
   ↓
5. Semver bump applied; changelog entry written
   ↓
6. PR reviewed and merged

Breaking Change Policy (semver)

Never introduce a MAJOR change without a migration guide.

---

Storybook as Living Documentation

Storybook is the primary documentation surface for ol_ui_library:

• Each component has a dedicated story file: ComponentName.stories.tsx
• Stories cover: default, all states, all variants, error conditions, accessibility states, edge cases
• The Docs addon generates interactive documentation from story metadata
• Stories serve as the baseline for visual regression testing (Chromatic or equivalent)

Minimum Story Coverage

Every component story must include:

---

Accessibility Standards

All components in ol_ui_library must meet WCAG 2.2 AA minimum. The POUR framework organises every requirement into four pillars:

Hard Requirements (Level AA)

Implementation Rules

• Native HTML first: <button>, <a>, <input> carry accessibility semantics for free. Use ARIA only when there is no native element for the role.
• Focus trapping: Components that manage focus (modals, dropdowns, tooltips) must trap focus within the component while open and return focus to the trigger element on close.
• Functional images: alt text describes the image's function, not appearance. Decorative images: alt="".
• Form errors: aria-describedby links the input to its error message. Error summary at top of form focuses the first error field on submit.

Frontend Project Structure

Naming Convention: frontend/

Use `frontend/` as the canonical name for the UI layer in every project.

This applies at every level: top-level project folders, CI/CD config paths, Docker compose service names, import alias roots, and README references.

---

Structure 1: Product Application (uses ol_ui_library)

For any product built on top of ol_ui_library. Uses Feature-Sliced Design adapted for the OL platform.

my-product/
  frontend/
    src/
      app/                      Application bootstrap — runs once at startup
        providers.tsx           React Query, theme, auth, error boundary providers
        router.tsx              Route definitions (React Router / TanStack Router)
        App.tsx                 Root component: wraps providers around router
        main.tsx                Entry point: renders App into the DOM
      pages/                    Route-level thin shells — one file per route
        dashboard/
          DashboardPage.tsx
        upload/
          UploadPage.tsx
        pipeline/
          PipelineDetailPage.tsx
      features/                 User-facing business capabilities
        document-upload/
          DocumentUploadFeature.tsx     Orchestrates the upload journey
          useDocumentUpload.ts          Upload logic: validation, API calls, state
          documentUpload.constants.ts   Accepted types, size limits, copy strings
          documentUpload.types.ts       Feature-local types
        pipeline-wizard/
          PipelineWizardFeature.tsx
          usePipelineWizard.ts
          pipelineWizard.constants.ts
          pipelineWizard.types.ts
        pipeline-monitoring/
          PipelineMonitoringFeature.tsx
          usePipelineMonitoring.ts
          usePipelineLogStream.ts
        results-review/
          ResultsReviewFeature.tsx
          useResultsFilter.ts
      entities/                 Business domain entities — shared across features
        document/
          document.types.ts           TypeScript types for the Document entity
          document.api.ts             React Query query/mutation definitions
          DocumentSummaryCard.tsx     Entity-level presentational component
        pipeline/
          pipeline.types.ts
          pipeline.api.ts
          PipelineStatusBadge.tsx
        result/
          result.types.ts
          result.api.ts
      shared/                   Cross-cutting — no feature-specific code here
        ui/                     Local component compositions (thin; prefer ol_ui_library direct)
        hooks/                  Truly shared hooks used by 2+ features
          useDebounce.ts
          usePageTitle.ts
        api/                    API client setup, interceptors, base URL, auth headers
          client.ts
          queryClient.ts
        utils/                  Pure functions: formatters, validators, date helpers
          formatBytes.ts
          formatDate.ts
        constants/              App-wide constants (route paths, feature flags)
          routes.ts
          config.ts
        types/                  Shared TypeScript types used across layers
          api.types.ts
          pagination.types.ts
    public/                     Static assets: favicon.ico, og-image.png, robots.txt
    e2e/                        Playwright end-to-end journey tests
      fixtures/                 Static test data files (sample.pdf, test.csv)
      journeys/                 Journey test specs named after the journey
        document-upload.spec.ts
        pipeline-wizard.spec.ts
        pipeline-monitoring.spec.ts
    .storybook/                 Only if the product team builds product-specific stories
    index.html
    package.json
    tsconfig.json
    vite.config.ts
    vitest.config.ts
    playwright.config.ts
  backend/
  docs/

Layer Import Rules (strictly enforced)

Each layer may only import from layers below it in this list:

pages       → features, entities, shared
features    → entities, shared
entities    → shared
shared      → (external packages only; no internal cross-imports)
app         → pages, shared

features never import from other features. entities never import from features.

Path Aliases (tsconfig.json)

{
  "compilerOptions": {
    "paths": {
      "@/*":     ["./src/*"],
      "@olui/*": ["../../ol_ui_library/src/*"]
    }
  }
}

Use @/features/document-upload/... not ../../../features/document-upload/.... Use @olui/atoms/Button not ol-ui-library/src/atoms/Button.

---

Structure 2: ol_ui_library Itself

For work on the shared component library. Uses Atomic Design with strict co-location.

ol_ui_library/
  src/
    atoms/                     Level 1 — smallest indivisible elements
      Button/
        Button.tsx
        Button.test.tsx
        Button.stories.tsx
        Button.module.css
        index.ts               Public export: export { Button } from './Button'
      Input/
      Label/
      Icon/
      Badge/
      Spinner/
      Avatar/
      Tooltip/
    molecules/                 Level 2 — functional combinations of atoms
      FormField/
        FormField.tsx
        FormField.test.tsx
        FormField.stories.tsx
        FormField.module.css
        index.ts
      FileDropZone/
      ProgressBar/
      SearchBox/
      Alert/
      Pagination/
    organisms/                 Level 3 — complex compositions of molecules and atoms
      DataTable/
        DataTable.tsx
        DataTable.test.tsx
        DataTable.stories.tsx
        DataTable.module.css
        useDataTable.ts        Co-located hook (used only by DataTable)
        dataTable.constants.ts
        index.ts
      DocumentUploader/
      NavigationBar/
      ChartPanel/
      WizardContainer/
    templates/                 Level 4 — structural page layouts; no data, no domain logic
      DashboardTemplate/
        DashboardTemplate.tsx
        DashboardTemplate.stories.tsx
        DashboardTemplate.module.css
        index.ts
      WizardTemplate/
      ResultsTemplate/
      EmptyStateTemplate/
    tokens/                    Design tokens — the visual vocabulary of the library
      colours.css              --color-brand-primary, --color-status-error, etc.
      spacing.css              --space-1 through --space-16
      typography.css           --font-size-sm, --font-weight-semibold, etc.
      borders.css              --radius-sm, --radius-md, --radius-full
      shadows.css              --shadow-sm, --shadow-md, --shadow-focus
      z-index.css              --z-modal, --z-tooltip, --z-dropdown
      tokens.css               Master file: @import all token files above
    hooks/                     Shared hooks exported by the library
      useDebounce.ts
      useMediaQuery.ts
      useLocalStorage.ts
      usePrevious.ts
    types/                     TypeScript types exported by the library
      component.types.ts       Base prop types: Size, Intent, etc.
      token.types.ts
    utils/                     Pure utility functions exported by the library
      formatBytes.ts
      formatDuration.ts
      accessibility.ts         Shared ARIA helpers
    index.ts                   Library barrel export — the public API of the library
  .storybook/
    main.ts
    preview.ts                 Injects tokens.css; global decorators
  e2e/                         Playwright tests for complex multi-step component interactions
  package.json
  tsconfig.json
  vite.config.ts               Also the Storybook build target
  vitest.config.ts

Component Folder Rule

Every component in ol_ui_library lives in its own folder with exactly these files:

Never add a component file without all required files. A component without tests or stories is not complete.

---

File Naming Conventions

Consistent across both product applications and ol_ui_library:

No abbreviations: document-upload/ not doc-upload/, pipeline-wizard/ not pipe-wiz/.

---

What Goes Where: Decision Table

Rule of thumb: If in doubt about placement, ask "which layer is this responsible to?" A component that knows about Pipeline domain types belongs in entities; a component that orchestrates the pipeline kick-off journey belongs in features.

UX Journey Design Patterns

What Is a UX Journey?

A UX journey is a named, multi-step user interaction that achieves a specific business outcome. Journeys are architectural concerns — they define component boundaries, state machine requirements, error handling strategies, and progress models.

Journey Anatomy

Every journey must specify all of these:

Design error paths first — error states are harder than happy paths. Leaving them to implementation leads to poor UX that is expensive to fix.

---

Document Upload Journey

Use when: User uploads one or more files to trigger a downstream process.

Component Architecture

DocumentUploader (organism)
├── DropZone (molecule)           drag-and-drop zone + "Browse files" button
├── FileList (molecule)           selected files with status indicators + remove controls
│   └── FileItem (molecule) × n  filename, size, status, per-file progress, error message
├── UploadProgress (atom)         overall progress bar (optional, for bulk uploads)
└── UploadSummary (molecule)      completion state: success / partial success / failed

Step Design

UX Rules

• Provide both drag-drop AND a "Browse files" button — both must be equally discoverable
• Show specific error messages: "invoice.pdf exceeds 5 MB" not "Upload failed"
• Support multi-file selection; never force one-at-a-time uploads
• Show per-file progress bars, not only an overall bar
• Allow removal of individual files from the list before upload begins
• After upload: distinguish between "file received" and "file processed"

State Machine (design this explicitly)

idle → files_selected → uploading → complete
                      ↘           ↗ (all files) → success
                        failed_partial → (some files) → partial_success
                        failed_all → error

---

Pipeline Kick-Off Journey (Wizard Pattern)

Use when: User configures and initiates a data processing pipeline. Best for complex configuration that can be logically segmented into steps.

When to Use a Wizard

Use a wizard when:

• The task is long and unfamiliar to most users
• Information entry is logically segmentable
• Subsequent steps depend on earlier answers
• The process is completed infrequently (not a daily workflow)

Do NOT use a wizard for: short forms (< 9 fields total), expert daily workflows, or processes that benefit from seeing all fields simultaneously.

Component Architecture

PipelineWizard (organism)
├── StepIndicator (molecule)       current step + total steps ("Step 2 of 4")
├── StepContainer (template)       renders the active step component
│   ├── PipelineConfigStep         parameters, run name, schedule options
│   ├── SourceSelectionStep        input data selection (file, dataset, query)
│   ├── ReviewStep                 read-only summary of all inputs (editable via links)
│   └── SubmitStep                 final confirmation; submit button; SLA estimate
├── WizardNavigation (molecule)    Back / Next / Submit with loading states
└── AbandonConfirmation (molecule) "Unsaved changes — are you sure?" on exit

Wizard Design Rules

• Maximum 5–9 fields per step; 1–2 minutes per step target
• Each step has one clear, self-contained goal — if a step is doing two things, split it
• Show clear progress: "Step 2 of 4 — Select your data source"
• Explain why information is needed — users abandon when they don't understand the value
• Always include a review/summary step before final submission
• Allow editing any previous step directly from the review step
• Back navigation never loses the current step's input
• Next validates the current step before advancing — show inline errors, not a toast

Step States (design all of these)

---

Pipeline Monitoring Journey

Use when: User watches the progress of a running or recently completed pipeline.

Component Architecture

PipelineDashboard (template)
├── StatusHeader (organism)        pipeline name, overall status badge, elapsed time
├── StageProgressTimeline (organism) per-stage status in sequence
│   └── StageCard (molecule) × n  stage name, status, duration, record count, log excerpt
├── MetricsPanel (organism)        key metrics: records in/out, error rate, throughput
└── LogStream (organism)           filterable, searchable log output

Information Architecture

• F-pattern layout: most critical status in the top-left
• Priority order: Overall Status → Stage Breakdown → Metrics → Logs
• Real-time updates for in-progress pipelines; static snapshot for completed
• Error states are visually prominent — not hidden inside a log viewer

Pipeline Status States (design all explicitly)

Real-Time Update Architecture

See references/data-visualisation-strategy.md for the full real-time strategy. Key constraints to specify at design time:

• Update frequency: how often does the UI poll/receive updates?
• Data retention: how many historical log lines / metric points does the browser hold?
• Reconnection strategy: what does the UI show if the WebSocket drops?

---

Results Review Journey

Use when: User reviews the output of a completed pipeline or data process.

Component Architecture

ResultsDashboard (template)
├── SummaryPanel (organism)         run metadata + key metrics at a glance
├── DataExplorer (organism)         filterable, sortable, paginated results table
├── VisualisationPanel (organism)   charts appropriate to data type (see data-visualisation-strategy.md)
└── ExportControls (molecule)       download (CSV/Excel/JSON) + share options

Information Architecture Rules

• Lead with the answer: summary metrics before raw data
• Group related information with visual separators
• Progressive disclosure: summary → detail → raw data
• Filters appear above the content they affect, with short plain labels
• Top 3–4 metrics aligned with the user's primary objective, not what is easy to count
• Empty states are designed — "No results found" includes a reason and a recovery action

---

General UX Journey Rules

1. Design error paths alongside happy paths — both are first-class requirements 2. Every step has one goal — split steps that are doing two things 3. Progress is always visible — users know where they are and how far they have to go 4. Back never destroys input — backward navigation preserves all state 5. Abandonment is graceful — explicit confirmation before losing progress; offer resume where feasible 6. Accessibility is per-step — keyboard navigation and screen reader behaviour are specified for each step, not for the journey as a whole 7. Loading states are designed — every async operation has a designed loading state; never leave the user staring at a frozen UI