Sefism is free for learners. We are here to help you grow, one step at a time.Join for free
Sefism.
Web

Documented Design System with Tokens and Storybook

A small, complete design system for a real product team or open source app: design tokens with light and dark modes, eight accessible React components with every state, Storybook documentation and one real screen rebuilt with it. A final year project where a designer and a developer split the work the way product teams do.

Topics
Difficulty

Intermediate

A small team, or one strong student willing to learn something new.
Effort

1 semester · 2 students (one design, one development)

Deliverables

8 to ship

3 optional extras

Suggested stack

Figma variablesTypeScript and ReactStyle Dictionary (DTCG token format)CSS custom properties or Tailwind CSSRadix Primitives or shadcn/uiStorybook with the a11y addonGitHub Actions
A suggestion, not a requirement. Swap anything for what you already know.

What you should ship

  • A UI inventory of one real app, counting button styles, greys, font sizes and spacing values, written up as the case for the system
  • Primitive and semantic tokens for colour, type, spacing and radius in one source file, built to CSS variables and mirrored in Figma variables, with light and dark modes
  • Eight components (button, text input, select, checkbox, dialog, toast, card, tabs) in Figma with variants and in code with matching prop names
  • Every component state designed and built: default, hover, focus, pressed, disabled, loading and error where relevant
  • A Storybook with a story per state and a documentation page per component: when to use it, when not to, and accessibility notes
  • Automated accessibility checks in CI plus a written keyboard-only and screen reader pass for each component
  • One real screen rebuilt with the system, with before and after screenshots and a count of removed one-off styles
  • A contribution guide explaining how to propose a component or change a token, and a versioned release with a changelog

If you have time left

  • A second brand theme created only by changing semantic tokens, with no component code touched
  • Visual regression tests on every pull request using Playwright screenshots or Lost Pixel
  • Round-trip token sync between Figma and the repository through Tokens Studio or the Figma variables API

The problem with inconsistent product UI

Most small product teams do not have a design system. They have a Figma file that drifted from the code a year ago, eleven shades of grey, four button styles that do nearly the same thing, and dialogs that trap keyboard users. Every new screen is built by copying the nearest old screen, so inconsistency compounds. The people who feel it are the startup with two designers and five developers, the university IT team maintaining a student portal, and the open source project whose contributors each style things their own way.

A design system fixes this by turning design decisions into shared, named values (tokens) and shared, tested components. Building a small one end to end teaches tokens, component API design, accessibility, documentation and collaboration, and it produces portfolio work a designer and a developer can both show.

What already exists and the gap

  • Shopify Polaris, IBM Carbon and the GOV.UK Design System are mature public systems with excellent documentation. They are great references but are built for their own products and brands.
  • Style Dictionary turns a token source file into CSS, JavaScript and platform formats, and supports the Design Tokens Community Group (DTCG) format, whose first stable version was published in October 2025.
  • Tokens Studio for Figma stores tokens as JSON and syncs them with GitHub, and Chromatic runs visual tests on Storybook stories.

The gap is not tooling. It is that small teams never connect these pieces for their own product: tokens named by purpose, components that match Figma prop for prop, and documentation that says when not to use something. Your project does exactly that for one real app, small and complete.

What you build

Pick a real client: a student society app, a startup a friend works at, or an open source web app with visibly inconsistent UI. Then build:

  • Tokens: primitive tokens (the raw palette and scales) and semantic tokens (color.text.muted, color.surface.raised) in one DTCG-style JSON file, built into CSS variables with light and dark modes.
  • Components: eight components on an accessible headless library, styled only with semantic tokens.
  • Figma library: the same components with variants and properties named like the code props.
  • Storybook: a story per state and a docs page per component.
  • Adoption: one real screen rebuilt with the system.

The users are the two sides of a product team: designers consume the Figma library, developers install the package, and both read Storybook.

The technically interesting part

The hard part is the token architecture and keeping design and code in sync. Naming is an engineering decision: if a component references blue-600 directly, a dark mode or rebrand touches every component. If it references color.action.primary, one change in the semantic layer flows everywhere. Show your evaluators a token graph (primitive to semantic to component) and prove it by switching themes without touching component code.

The second hard part is accessible components with every state. A dialog must trap and restore focus, close on Escape and announce its title. A select must work with a keyboard and a screen reader. Building on Radix or shadcn/ui gives you the behaviour; your job is to not break it with styling and to document it.

How to evaluate it

  • Token coverage: zero hard-coded colour or spacing values in component code, checked by a lint rule in CI.
  • Theme test: change one semantic token and screenshot every story before and after; switch to dark mode and count broken stories (target zero).
  • Accessibility: automated axe checks pass on every story; manual keyboard and screen reader checklist completed per component; all text meets WCAG AA contrast in both modes.
  • Adoption: on the rebuilt screen, count unique colours, font sizes and custom CSS rules before and after.
  • Usability for developers: give three developers a small task (build a form with validation) using only Storybook docs; record time and questions asked.

Suggested plan

  1. Weeks 1 to 2: UI inventory of the chosen app, agree token names and component props as a pair.
  2. Weeks 3 to 4: token source file, build pipeline, light and dark modes in code and Figma.
  3. Weeks 5 to 9: components in Figma and code side by side, one or two per week, with stories.
  4. Weeks 10 to 11: accessibility pass, docs pages, CI checks.
  5. Weeks 12 to 13: rebuild one real screen and run the developer task test.
  6. Weeks 14 to 15: release, changelog, final report.

Path to a product

The realistic first customer is the team whose app you rebuilt: they keep the system and you maintain it. From there, the paths are consulting (set up tokens and a starter system for small SaaS teams), an open source starter kit that other teams adopt, or a paid Figma and code kit sold as a one-time licence. At minimum it is a portfolio centrepiece that gets frontend and design engineering interviews.

Scope warning

Do not build forty components with only a default state. Do not write your own headless dialog or select from scratch. Do not build a token editor or a Figma plugin in version one. Eight components with every state, good docs and one real adoption beat a large half-finished library.

Learn what you need on Sefism

Get help with this idea

The most common failure here is scope: too many components and no real adoption. Tauseef can help you pick the right client app, agree token names and props before you split the work, and set up an evaluation your examiners will take seriously. If you are new here, create a free account first.

Ideas and guidance, not finished projects

These are project ideas and scoping guidance, published free for students to use as a starting point. I do not build, write, or sell final-year projects, and I do not complete coursework for anyone. Take an idea, make it yours, and build it.

Not sure this one fits you?

I help students pick an idea that matches their skills and their deadline, then scope it down until it is finishable. Guidance only, never done for you.

Discuss this idea
Work with me

Stuck on something specific?

Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.

Book a free sessionSee all services

Follow along

New writing, resources and project ideas land here first.