ap-ds-storybook

Andrew's personal design system: components, foundations (color, border, typography), and design tokens, authored in Figma via the Token Studio plugin, built into CSS with Style Dictionary, presented in Storybook, and published to npm as ap-ds-storybook for use in other projects.

Live Storybook: https://andrewjypark.github.io/ap_ds_storybook/

For this repo's older build/architecture history (from before it was renamed from ap_ui_kit), see HISTORY.md.

What's in the package

Components (exported from the package root): Button, Checkbox, Dropdown, Icon, Modal/ModalBanner, Radio, SegmentGroup, TableCell/TableRow, TextInput, Tooltip, ViewportSync.

Every component's CSS variables follow the --ap-tier-3-<component>-* naming convention (e.g. --ap-tier-3-button-color-background-default), generated by build-tokens.js from tokens.json's tier_3_*-prefixed token groups.

Installing in another repo

npm install ap-ds-storybook@latest

When upgrading, name the package explicitly (npm install ap-ds-storybook@^1.x) or run npm update ap-ds-storybook — a plain npm install won't pick up a newer version if package-lock.json already satisfies the existing semver range.

Wire it in

The package ships JSX source, not a pre-built bundle. For Next.js, add it to transpilePackages in next.config.mjs/next.config.ts:

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['ap-ds-storybook'],
};
export default nextConfig;

For a non-Next.js project, just make sure your bundler processes JSX/ESM from node_modules/ap-ds-storybook.

Import the compiled runtime CSS, set the theme via a data attribute, and mount <ViewportSync /> once near the root of whatever layout uses the design system — every token is scoped to a [data-theme][data-viewport] selector block, not :root:

import "ap-ds-storybook/build/all-combinations/css/variables.css";
import { ViewportSync } from "ap-ds-storybook";

export default function ApLayout({ children }) {
  return (
    <div data-theme="core">
      <ViewportSync />
      {children}
    </div>
  );
}

Don't hardcode data-viewport. Every responsive token switches on the [data-theme][data-viewport] attribute, not an @media query, so a hardcoded value never responds to the browser resizing. <ViewportSync /> writes the correct data-viewport onto <html> on mount and on every resize — leave data-viewport off entirely and let it manage that attribute. Only data-theme is a deliberate per-app choice.

Available themes: core, basil, molasses (plus _dark and _dark_bg_neutral variants). Available viewports (set automatically, not by hand): desktop, tablet, mobile. Confirm current options against node_modules/ap-ds-storybook/build/ if unsure — these grow as the design system does.

Load the theme's fonts

The webfonts ship in the package under assets/fonts/, but variables.css does not load them: it only references family names (e.g. 'Basier Circle'). Import the @font-face stylesheet for each family your theme uses, or the browser falls back to whatever is installed locally. On Andrew's Mac, the local Basier and Novela installs have duplicate copies that render as tofu boxes (squares with ?).

| Theme | font1 | font2 | font3 | | --- | --- | --- | --- | | core | twk-lausanne | twk-continental | novela | | basil | basier-circle | basier-square | basier-square-mono | | molasses | nudica | quablo | bricolage-grotesque |

The _dark variants use the same fonts as their base theme.

With a bundler (Next.js, Vite): import the CSS next to variables.css:

import "ap-ds-storybook/build/all-combinations/css/variables.css";
// basil:
import "ap-ds-storybook/assets/fonts/basier-circle/basier-circle.css";
import "ap-ds-storybook/assets/fonts/basier-square/basier-square.css";
import "ap-ds-storybook/assets/fonts/basier-square-mono/basier-square-mono.css";

Plain static HTML (no build step): link the same files from jsDelivr, pinned to the installed version:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/assets/fonts/basier-circle/basier-circle.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/assets/fonts/basier-square/basier-square.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/assets/fonts/basier-square-mono/basier-square-mono.css" />

If you switch themes at runtime, load the fonts for every theme you switch between.

Import components from the package root:

import { Button, Modal, TextInput, ViewportSync } from "ap-ds-storybook";

Optional: VS Code autocomplete for --ap-* tokens

Third-party CSS-variable autocomplete extensions and VS Code's built-in css.customData don't reliably work for this (unresolvable caching bugs / no var(...) support). Instead, generate a native VS Code snippets file from the package's single-theme reference CSS:

npx ap-ds-storybook-snippets

This writes a project-level .vscode/*.code-snippets file from node_modules/ap-ds-storybook/build/tier_1_core/css/variables.css. Re-run it any time the installed version changes. Pair it with "editor.snippetSuggestions": "bottom" under [css]/[scss]/[less] in settings.json so the ~1,500 generated snippets don't crowd out normal property/value completions.

Fuller background on this (including why the third-party extension approach was dropped) lives in the install-ap-design-system skill and in the Claude Project "Codegrid Projects + Next Js Tutorials" (ap-ds-storybook/packaging-and-autocomplete-retrospective.md, ap-ds-storybook/install-guide-for-new-repos.md).

Developing this repo

npm install
npm run build             # node build-tokens.js + the color/border/typography manifest scripts
npm run storybook          # builds tokens, then starts the Storybook dev server on :6006
npm run build-storybook    # builds tokens, then produces a static storybook-static/ build
npm run deploy-storybook   # publishes storybook-static/ to GitHub Pages (the gh-pages branch)
npm run test:a11y          # starts storybook-static/ and runs axe-core accessibility checks against it

Publishing Storybook (the docs site)

npm run build-storybook && npm run deploy-storybook

Pushes storybook-static/ to the gh-pages branch; GitHub Pages serves straight from it. Live at the URL above — this changes if the GitHub username or repo name is ever renamed.

Continuous Integration

.github/workflows/ci.yml runs on every push to main and every PR: a build check (npm run build-storybook) and an accessibility check (one Playwright test per story, scanned with @axe-core/playwright). Worth knowing: pushes go straight to main with no branch protection or PR review, so CI is the gate standing in for both.

Publishing a version update to npm

Use this after making changes to the design system itself (new component, token change, bug fix) that should ship to consumers.

1. Confirm you're authenticated: npm whoami. A 404 on npm publish is almost always really a 401 Unauthorized underneath — if npm whoami fails, run npm login first.
2. Bump the version in package.json (npm version patch|minor|major, or edit by hand) and confirm it actually persisted on disk before publishing — an editor buffer autosaving over a hand-edited package.json shortly after can silently revert the bump.
3. Publish:

   npm publish

   This may trigger a one-time-password or browser-based approval step for your npm account — watch for a browser tab or your authenticator app.
4. Read the result, don't guess from npm view:
   • exit 0 / info ok in the log (or the + <pkg>@<version> line) means it worked, even if the package is still "being processed."
   • npm view ap-ds-storybook version lagging behind right after a successful publish is registry propagation delay, not a failed publish — wait a bit and re-check rather than re-publishing.
   • 409 Conflict: Cannot publish over previously staged version means that exact version number is permanently unusable (an earlier attempt partially staged it) — bump to the next version and publish that instead. There's no way to "unstage" it.
   • 403 Forbidden: Cannot publish over the previously published versions: X.Y.Z after you were sure you'd bumped the version usually means the bump didn't actually stick on disk — re-edit it, re-read the file fresh to confirm, then retry.

After a publish that adds or changes something consumer-facing, also update ap-ds-storybook/install-guide-for-new-repos.md in the "Codegrid Projects + Next Js Tutorials" Claude Project so future installs elsewhere pick up the change, and check whether the install-ap-design-system skill itself needs updating.