---
title: Codifying UX with Storybook
description: R&D approach for using Storybook to define, share, validate, and evolve Thinking Cap user experiences across application repositories.
created: 2026-10-05
updated: 2026-10-05
authors: ThinkingCap
topics: [Research Development]
status: published
canonical: https://console.thinkingcap.com/guest/Research-Development/UX/Storybook/Storybook-UX-Rules
lastmod: 2026-10-05
---

# Codifying UX with Storybook

Storybook is the working specification for how Thinking Cap experiences look and behave. It gives us a place to define UX independently from a complete application page, document the states an object can appear in, validate accessibility and responsive behaviour, and deliberately reuse patterns across Console, Guest/R&D, Surface, and Learner Views.

The goal is not to create one universal interface. The goal is to create a shared UX language while allowing each experience and each Learner View theme to express the context and brand it needs.

## Why we are doing this

Today, the same concepts can appear in several Thinking Cap applications. A user, activity, learner record, navigation pattern, button, table, status, or other object may need to behave consistently even when it is rendered in a different experience.

Storybook gives us a deterministic layer between UX intent and application implementation. It lets us define what an object is, which states matter, how each state should render, which components it uses, and which foundation rules govern those components.

This gives us a practical way to:

- codify UX decisions rather than leaving them implicit in application code;
- design and review components and objects in isolation;
- make required states visible, testable, and reusable;
- establish accessibility and responsive expectations before a pattern is used broadly;
- reduce unnecessary custom CSS and one-off implementations;
- preserve intentional differences between experiences and customer themes;
- make UX changes easier to assess across experiences.

## Storybook topology across Thinking Cap

Each product experience maintains its own Storybook alongside the application it documents. This keeps the UX specification close to the implementation while allowing shared patterns to be carried consistently across experiences.


The model covers four primary experience contexts:

| Experience | Storybook responsibility |
| --- | --- |
| Admin Experience | Administrative workflows, surfaces, objects, states, and Thinking Cap-branded foundation values |
| Guest Experience | Guest and R&D experiences, public/verified states, surfaces, objects, and Thinking Cap-branded foundation values |
| Surface Experience | Surface experience patterns, objects, states, and Thinking Cap-branded foundation values |
| Learner Views | Learner experience patterns plus customer-specific theme values |

Learner Views use the same UX architecture but allow the foundation values to vary by customer. The structure of the theme is shared. The values are not required to be identical.

### What is shared and what is local

We replicate deliberately, not indiscriminately.

**Components** are replicated between relevant experiences when the behaviour and API should remain aligned.

**Stories** are replicated when the same object and state exist in more than one experience. A shared story should represent the same underlying UX contract even when an experience adds contextual information.

**Theme structure** is replicated across experiences so the same kinds of design decisions are represented consistently. Console, Guest/R&D, and Surface use Thinking Cap brand values. Learner Views use customer-specific values within that common structure.

This is deliberate reuse across product experiences, not a requirement for a single runtime Storybook or a single shared theme.

## The UX model

We use a hierarchy that moves from the experience down to the design foundation:

**Experience → Region → Surface / Subsurface → Object → Story → Component → Foundation**

The exact middle layers depend on the experience. The important distinction is that each layer answers a different question.

| Layer | What it defines |
| --- | --- |
| Experience | The application context, such as Console, Guest/R&D, Surface, or a Learner View |
| Region | A persistent area of the experience, such as Header, Assistant, or Workspace |
| Surface | A navigable workspace or page-level experience, such as Home, Activities, Resources, or My Transcript |
| Subsurface | A meaningful view within a surface when another level is required |
| Object | A product concept rendered in the experience, such as a user, activity, learner record, message, or resource |
| Story | A defined presentation of an object or component in a particular state or context |
| Component | A reusable UI building block used to construct stories and surfaces |
| Foundation | Theme tokens and UX rules such as typography, colour, spacing, radius, states, and accessibility constraints |

This hierarchy prevents us from treating a component library as the UX specification. Components are building blocks. Stories codify meaningful product states. Objects and surfaces establish how those stories participate in the product experience.

## From object and state to Story

Stories should be driven by product meaning, not by arbitrary visual variations. We begin with an object, identify the states that materially change its presentation or behaviour, and create a named Story for each state that needs to be designed, tested, or reused.

![From object and state to Story](./assets/ux-storybook-objecttostory.png)

For example, a learner record may need stories for `notstarted`, `inprogress`, `completed`, and `incomplete`. An activity may need `notenrolled`, `enrolled`, `locked`, and `expired`. A user may need `active`, `inactive`, and `pending`.

A story name should be deterministic enough that we can infer what it represents from the object and state. For example:

```text
learnerrecord.scorm.notstarted
learnerrecord.scorm.inprogress
learnerrecord.scorm.completed
learnerrecord.scorm.incomplete

activity.notenrolled
activity.enrolled
activity.locked
activity.expired

user.active
user.inactive
user.pending
```

Object-specific qualifiers can be added when they represent a meaningful behavioural difference. For example, SCORM, H5P, LTI, instructor-led, attestation, and survey learner records may share common states while requiring different story content.

### Stories are UX contracts

A Story should answer more than “what does this component look like?” Where applicable, it should make visible:

- the object's required data;
- its state and state-specific actions;
- status and progress treatment;
- empty, loading, error, locked, unavailable, or permission-dependent behaviour;
- responsive behaviour;
- keyboard and focus behaviour;
- accessible name, semantics, contrast, and other relevant accessibility expectations;
- theme-sensitive presentation;
- any experience-specific information layered onto a shared object.

When the same story is used in another experience, the core object state should remain recognizable. The consuming experience may add context. For example, an Admin learner-record story may expose suspend data or CMI interactions that are not appropriate in the Learner View without redefining what “completed” means.

## Shared UX, different experiences

The Storybook model gives us a common UX vocabulary without flattening the differences between products or customers.

![Shared UX across Thinking Cap experiences](./assets/ux-storybook-sharedux.png)

The shared model works in two directions:

1. **Top down:** the experience and region establish context for surfaces and objects.
2. **Bottom up:** foundation values govern components, components construct stories, and stories construct objects and surfaces.

Console, Guest/R&D, Surface, and Learner Views can therefore share the same object behaviours and component expectations while rendering them within different navigation, workflows, permissions, and themes.

For Learner Views, customer branding primarily changes the foundation values. It should not require us to redefine the UX architecture or create customer-specific behaviour when the underlying product behaviour is the same.

## Foundation and theming

The Foundation layer defines the variables and rules that should be applied consistently before individual stories introduce local styling. It includes, at minimum:

- colour palettes for light and dark modes;
- typography, including selected Google or custom font, platform system fallbacks, generic font family, and supported font weights;
- spacing scale;
- borders, radii, and shadows;
- link and control states, including normal, hover, active, focus, disabled, and where relevant visited;
- icon usage, including Font Awesome conventions;
- layout and responsive rules;
- accessibility requirements, including focus visibility, contrast, semantic structure, keyboard operation, and reduced-motion considerations where relevant.

The theme schema should remain stable across experiences even when token values differ. This allows a Story to rely on a known theme contract rather than hard-coded application values.

## Component guidance

Storybook should cover the reusable primitives and composed components that materially affect UX. Current examples include typography, links, buttons, tabs, menus, chips, accordions, media, tables, progress indicators, charts, status treatments, and message patterns.

A component story is appropriate when the purpose is to document the component itself, its supported variants, states, API, accessibility, or responsive behaviour.

An object story is appropriate when components have been composed into a recognizable Thinking Cap product concept with product-specific data and state.

We should avoid using Storybook merely as a gallery of every possible CSS variation. Variants should exist because they support a defined UX need.

## Accessibility as part of the definition

Accessibility is part of the Story, not a final audit step. The Storybook accessibility tooling should help identify issues while the pattern is still isolated and easy to correct.

For each relevant Story, we should be able to validate the expected keyboard path, visible focus, semantic roles and labels, colour contrast, content at responsive widths, and behaviour when text or content expands.

Automated checks do not replace manual accessibility review, but they give us a repeatable baseline and make regressions easier to detect.

## Working process

A UX change should normally move through Storybook before or alongside its use in an application surface:

1. Identify the experience, region, surface, and object affected.
2. Determine whether an existing object, story, component, or foundation rule already covers the requirement.
3. If a new product state is required, define the state and add or update its Story.
4. If the Story exposes a missing reusable primitive, add or update the component.
5. Apply foundation tokens and rules rather than introducing one-off styling where possible.
6. Validate responsive behaviour, interaction states, light/dark or customer theming as applicable, and accessibility.
7. Review the Story as the UX reference implementation.
8. Implement or consume it in the application surface.
9. Replicate shared changes to other relevant experiences when the same UX contract applies.

The sequence is intentionally bidirectional. Existing application behaviour can be brought into Storybook as we codify the current product, but once a pattern is codified, Storybook becomes the reference for subsequent UX work.

## Replication rules

Replication should follow meaning rather than visual similarity.

- Replicate a **component** when multiple experiences require the same behaviour and API.
- Replicate a **Story** when multiple experiences contain the same product object and state.
- Replicate the **theme schema** across all experiences.
- Do not force identical theme values across customer Learner Views.
- Do not copy an experience-specific workflow simply because it uses the same components.
- Extend a shared object Story with experience-specific data only when the underlying state remains the same.
- When a shared story changes meaning or behaviour, assess the impact on every experience that carries that story.

Until we automate synchronization, replication is an explicit development responsibility and should be visible in the scope of a UX change.

## Release model

Storybook lives alongside the application source it documents. Local Storybook development does not create a separately deployed production capability.

Changes to an experience Storybook follow the same release-management process as the application it supports. If a separately hosted or composed Storybook hub is introduced in the future, that hosting model can be reviewed as its own infrastructure and deployment decision without blocking current Storybook work.

## What success looks like

We will know this approach is working when a designer, developer, tester, or AI coding agent can start from a Thinking Cap product concept and reliably answer:

- What object is this?
- Which state is it in?
- Is there already a Story for that state?
- Which components construct it?
- Which foundation rules govern those components?
- Where else is the same Story or component used?
- Which differences are intentional because of the experience or customer theme?
- What responsive and accessibility behaviour is required?

At that point, Storybook is no longer just a component-development tool. It is an executable UX specification for Thinking Cap.

## R&D direction

The immediate R&D work is to codify the Learner Experience first as the proving ground for the architecture, naming model, theme schema, stories, and accessibility workflow. The same model can then be applied to Admin, Guest/R&D, and Surface while preserving clear product-experience boundaries.

The architecture should remain simple enough that teams can maintain it as part of normal product development. Shared UX is valuable only if the source of truth stays close to the code that actually renders the experience.