---
title: "Thinking Cap: Shared UI and Storybook Architecture"
description: Architecture reference 24 October 2026
created: 2026-10-24
updated: 2026-10-24
authors: ThinkingCap
topics: [Research Development]
status: published
canonical: https://console.thinkingcap.com/guest/Research-Development/UX/Storybook/Thinking_Cap_Storybook_Architecture_Guide
---

# Thinking Cap: Shared UI and Storybook Architecture

**Architecture reference | 24 October 2026**

## Decision and goal

Use one central `tc-storybook` application to review three experience shells (Admin, Guest, Learner) and a catalogue of Shared Stories. Reuse one authoritative production implementation of each genuinely shared UI component across independently deployed surface repositories. Storybook is a development, documentation and testing tool, **not** a production rendering service.

The implementation and packaging details must be confirmed by an audit of existing shared components and the `lv-site-template` distribution kit before migration.

## 1. Architecture

```mermaid
flowchart TB
  SB["tc-storybook<br/>Central catalogue and visual tests"]
  EX["Experience stories<br/>Admin | Guest | Learner shells"]
  SS["Shared Stories<br/>states, fixtures, contracts"]
  UI["Shared UI component package(s)<br/>production React components and theme tokens"]
  R1["tc-console"]
  R2["Admin Work Surfaces"]
  R3["lv-site-template"]
  R4["Learner Surfaces"]
  SB --> EX
  SB --> SS
  SS -. "renders and tests" .-> UI
  UI --> R1
  UI --> R2
  UI --> R3
  UI --> R4
```

**Direction of dependencies:** Surface applications import shared production components. Storybook imports those same components to render examples. Surface applications do not import Storybook or send production data to stories.

## 2. Storybook navigation

- **Admin Experience:** Shell; Shell / Header; Shell / Subheader; Shell / Assistant.
- **Guest Experience:** Shell; Shell / Header; Shell / Subheader; Shell / Assistant.
- **Learner Experience:** Shell; Shell / Header; Shell / Subheader; Shell / Assistant.
- **Shared Stories:** User Identity; Activity / Thumbnail / Enrolled; Activity / Thumbnail / Not Enrolled; Learning Path / Thumbnail / Enrolled; Learning Path / Thumbnail / Not Enrolled; Progress Bar; Pagination; Transcript variants; and additional approved reusable patterns.

These are four navigation sections inside **one** Storybook, not four Storybook installations. Experience shell stories can compose shared production components.

## 3. What lives where

| Asset | Authority |
|---|---|
| Storybook app, sidebar, documentation, cross-experience fixtures and visual testing | `tc-storybook` |
| Canonical shared component stories and state specifications | Central Shared Stories catalogue, with source ownership and validation defined during implementation |
| Reusable production components and their public TypeScript contracts | Shared UI package(s), location to be confirmed |
| Brand/theme tokens | Existing authoritative shared theme system |
| Shell composition and application-specific UI | `tc-console` and `lv-site-template` |
| Surface workflows, API integration, permissions and local composition | Individual Admin and Learner Surface repos |

A shared story is an example of a component, not the component itself. Centralizing stories alone does not distribute executable production UI. A common component can be shared only if surfaces consume the same implementation or compatible published package.

## 4. Example: progress bar

A developer needs a progress bar in a Learner Path surface. The AI development rules require searching the approved component registry. If `ProgressBar` exists, the surface imports it from the approved production package and passes LMS data through props.

```tsx
import { ProgressBar } from '@tc/ui'; // illustrative package name

<ProgressBar value={path.percentComplete} label="Learning path progress" />
```

Storybook separately renders the same component with representative fixtures (0%, 25%, 75%, 100%, error, loading, themes). **The live application never sends data to Storybook.** The story validates what the component should display for supplied inputs.

```mermaid
flowchart LR
  API["LMS/API data"] --> SUR["Learner Surface"]
  SUR --> UI["Shared ProgressBar"]
  FIX["Story fixtures"] --> STORY["Storybook story"]
  STORY --> UI
```

## 5. Example: transcript across four surfaces

Learner Transcript, Connections, Admin Users and Admin Activities may all need transcript UI. They should reuse a common transcript component or smaller transcript primitives (rows, completion status, credit summary) where contracts match. The surfaces retain responsibility for fetching records, permissions, actions, and context-specific composition. Admin-only capabilities can be explicit props or compositions, not duplicated implementations.

## 6. AI Development Bible rule

**Before creating or modifying UX, search the approved Storybook/component registry.**

1. **Exact match:** Import the approved shared production component. Use documented props and variants. Do not duplicate it.
2. **Partial match:** Propose a compatible extension, and update its component contract and stories together.
3. **No match:** Propose a new shared component and canonical stories when reuse is likely; otherwise justify a local component.
4. **Exception:** Record why a local implementation is needed (distinct behaviour, dependency, security, or performance constraints).
5. **Verification:** Run TypeScript checks, unit tests, accessibility checks, relevant Storybook stories and visual regression tests.

Make the catalogue machine-readable: component ID, package/import path, owner, props, variants, story IDs, status, and consuming repositories. AI review helps enforce reuse, but deterministic CI checks must cover imports, contracts and tests. A visual lookalike detector is not guaranteed.

## 7. How updates reach consuming surfaces

```mermaid
flowchart TD
  A["Shared component or approved UX contract changes"]
  B["Update implementation + canonical stories"]
  C["CI: type, unit, accessibility and visual tests"]
  D["Publish versioned component package"]
  E["Identify consuming repositories"]
  F["Automated dependency update PRs"]
  G["Run affected surface and integration tests"]
  H{"Compatible and approved?"}
  I["Merge and deploy affected surfaces"]
  J["Fix migration or reject change"]
  A --> B --> C --> D --> E --> F --> G --> H
  H -- Yes --> I
  H -- No --> J
  J --> G
```

- **Visual implementation change, same API:** Surfaces receive the new appearance after adopting and deploying the new shared package version.
- **New optional variant:** Existing surfaces continue working; surfaces opt into the new prop as needed.
- **Breaking contract change:** Update consumer code (possibly with codemods or AI-assisted PRs), test and approve before deployment.
- **Story-only change:** Does not change production UI. An approved UX change must include the corresponding implementation change or be marked as a proposal.

Use Renovate or Dependabot, or equivalent automation, to propose dependency updates. A dependency registry should be generated from actual package manifests and imports, not maintained only by hand. Do not auto-merge breaking changes without validation.

## 8. Branding and compatibility

Shared components consume existing design tokens and customer brand font stacks. They must not hardcode branded colours, fonts, radii or shadows. Storybook must test Admin, Guest and Learner contexts, light/dark configurations and accessibility. Story fixtures must not override customer branding to manufacture a passing appearance. Do not move production shell code into Storybook.

## 9. Migration from the current setup

**Known baseline:** `lv-site-template` already hosts a centralized Learner Storybook and distribution kit; the Credentials pilot has validated stories. Do not discard this work.

**Audit before modifying:**

1. Inventory Storybook configuration, distribution-kit generated files, story source locations and CI across `lv-site-template`, `tc-console` and participating surfaces.
2. Inventory existing shared UI packages, token ownership, package versions, import paths and cross-repository dependencies.
3. Identify canonical shared components, duplicates and surface-specific variants. Start with User Identity, ProgressBar, Activity Thumbnail and Transcript.
4. Decide how `tc-storybook` resolves components across repos: published versioned packages are preferred for reproducible builds; a controlled multi-repo workspace may support development.
5. Migrate the central Storybook application without changing runtime imports or deployment behaviour. Preserve validated Learner stories.
6. Add the three shell sections and Shared Stories catalogue, then enable visual/accessibility testing and dependency update automation.
7. Retire redundant Storybook kit infrastructure only after parity, consumer tests and rollback procedures are verified.

**Open decisions:** package ownership and publishing; registry generation; shared story source location; consumer version policy; visual test baseline approvals; rollout sequencing. These are implementation decisions, not facts already verified about current repositories.

## 10. Acceptance criteria

- One `tc-storybook` application shows Admin, Guest, Learner and Shared Stories sections.
- A surface can discover and import an approved component using a stable package contract.
- A canonical component renders consistently in at least two distinct consuming repositories and relevant themes.
- Component updates identify consumers and trigger tested update proposals.
- Story-only changes cannot silently redefine production UX.
- Surface repos remain independently buildable and deployable, without a runtime dependency on Storybook.
- Existing Learner Storybook work and production branding rules are preserved.