簡素 Kanso Protocol

Open source design system for Angular — and any framework via Web Components — built on architectural consistency.

Design tokens in W3C DTCG format serve as a single source of truth for both Figma and code. Rules are embedded in architecture, not in agreements. Native Angular components ship as @kanso-protocol/ui; the same components compile to framework-agnostic custom elements as @kanso-protocol/elements for React, Vue, or plain HTML.

Status: 5.x stable. Per the stability matrix, 40 of 61 surfaces are stable (API frozen for 5.x) and the rest beta (held by open API questions, not missing coverage); only virtual-list is still experimental. Pin exact versions in production. The 5.0 line consolidated the former 64 per-component packages into a single @kanso-protocol/ui package with per-component secondary entry points (ADR 0002) — install once, import per-subpath, tree-shaking preserved. Upgrading from 4.x? Follow the v5 migration guide (mechanical import-path change; no component API changed). See docs/roadmap.md for what's next and the changelog for what landed.

Why Kanso Protocol?

簡素 (kanso) — one of the seven principles of Japanese aesthetics — is the practice of restraint and the removal of the unnecessary. The library follows the same idea: a small, opinionated, internally consistent surface where the rules live in the code, not in conventions.

Every value is a token. Components never carry magic numbers or inline hex. CSS custom properties — generated from W3C DTCG tokens — are the single source of truth shared between Figma and code.
Every component follows the same anatomy. Container → Content → Element. New components don't introduce a new mental model.
Every state is explicit. Six named states (rest / hover / active / focus / disabled / loading), each with its own color and motion tokens.
No exception without a record. When a component departs from the contract, the deviation lives as an ADR with a reason — not as an undocumented one-off.
Designed to stay small. Components are added intentionally, when there's a clear need — not because something might be useful.
One package, per-component entry points. npm i @kanso-protocol/ui, then import each component from its own subpath (@kanso-protocol/ui/button). Tree-shaking ships only what you reference.
Not just Angular. The same components ship as framework-agnostic custom elements (@kanso-protocol/elements) — use <kp-*> from React, Vue, Svelte, or plain HTML. SSR-safe out of the box with @angular/ssr.
AI-native. Ships with @kanso-protocol/mcp — a Model Context Protocol server that exposes the live, typed catalog to Claude Code, Cursor, and VS Code, so the assistant authors Kanso UI from the actual API instead of from training-data guesses.

Live Preview

Storybook: gregnblack.github.io/kanso-protocol — every component, pattern and example page with autodocs, live controls, and a light/dark theme toggle.
Figma Community: figma.com/community/file/1633266134559104948 — the full design library; duplicate it into your team to use the components, variables, and example pages directly.

AI-native: ship with an MCP server

Kanso Protocol is one of the first design systems to ship a Model Context Protocol server out of the box — @kanso-protocol/mcp. Your AI assistant (Claude Code, Cursor, VS Code, any MCP-aware client) can introspect the entire catalog over stdio: every component's inputs / outputs / ARIA role / keyboard pattern, every pattern, every design token. No copy-pasting docs, no guessing prop names, no out-of-date snippets.

Install

The server runs via npx, so there's nothing to install globally — pick the snippet for your editor below.

Claude Code

One command from the project root:

claude mcp add kanso -- npx @kanso-protocol/mcp

…or, equivalently, drop this into your project's .mcp.json (create the file if missing):

{
  "mcpServers": {
    "kanso": { "command": "npx", "args": ["@kanso-protocol/mcp"] }
  }
}

Restart Claude Code, then run /mcp to confirm kanso appears as ✔ connected with 11 tools.

Cursor

Open Settings → Features → MCP → Add new MCP server, then fill:

Name: kanso
Type: command
Command: npx @kanso-protocol/mcp

…or edit ~/.cursor/mcp.json directly (project-scoped: .cursor/mcp.json in repo root):

{
  "mcpServers": {
    "kanso": { "command": "npx", "args": ["@kanso-protocol/mcp"] }
  }
}

VS Code (Continue, Cline, GitHub Copilot agent mode)

Add to the extension's MCP config — for Continue this is ~/.continue/config.json, for Cline it's the Cline MCP Servers settings panel. Same shape:

{
  "mcpServers": {
    "kanso": { "command": "npx", "args": ["@kanso-protocol/mcp"] }
  }
}

Other MCP-aware clients (Zed, Windsurf, Goose, custom)

Any client that speaks the MCP stdio transport works. Point it at:

command: npx
args:    ["@kanso-protocol/mcp"]

The server registers eleven tools at startup (catalog_overview, list_components, get_component, list_patterns, get_pattern, list_tokens, get_token, figma_context, figma_for_component, figma_for_pattern, figma_for_icon).

Try it

Once connected, ask your assistant things like:

"Which size ramp does kp-input support, and which validators does form-field translate by default?"
"List every --kp-color-* token tied to the danger role."
"I need a settings page with a sidebar of collapsible sections — which Kanso pieces compose that?"

The assistant calls list_components / get_component / list_tokens under the hood and answers from the live catalog. Full tool reference — including the Figma bridge tools (figma_for_component, figma_for_pattern, figma_for_icon) — lives in the package README.

Install & Use

New here? The getting-started guide takes you from install → tokens → first screen → a working form in five steps. It works with @angular/ssr out of the box.

Not on Angular? npm i @kanso-protocol/elements gives you the same components as framework-agnostic custom elements (<kp-badge>, <kp-card>, …) for React / Vue / plain HTML.

One package, per-component entry points. Install once; import only what you use — each entry point is a separate ESM module, so tree-shaking ships only what you reference.

npm install @kanso-protocol/ui

Load the tokens once in your app bootstrap. The primary distribution is CSS custom properties — all components consume them at runtime:

import '@kanso-protocol/ui/styles/tokens.css';
import '@kanso-protocol/ui/styles/dark.css';   // optional — enables [data-theme="dark"]

Sass / SCSS consumers can also import the equivalent compile-time $kp-* variables (handy for projects that haven't migrated to CSS custom properties yet):

@use '@kanso-protocol/ui/styles/tokens' as *;   // exposes $kp-color-blue-600 etc.

Both files are generated from the same DTCG source; pick whichever fits your stylesheet pipeline. Components themselves only depend on the CSS variables — they work identically regardless of which import you choose.

Recolor to your brand in one line — npm run theme:brand -- "#7C3AED" > brand.css, load it after tokens.css, and all 114 accent-derived tokens cascade with no rebuild. Light/dark, multi-brand, and fully-custom themes are covered in the theming guide.

Use the component as a standalone Angular import:

import { Component } from '@angular/core';
import { KpButtonComponent } from '@kanso-protocol/ui/button';

@Component({
  standalone: true,
  imports: [KpButtonComponent],
  template: `<kp-button color="primary" (click)="save()">Save</kp-button>`,
})
export class MyFeatureComponent { save() { /* ... */ } }

Switch themes by toggling data-theme on <html> or <body>:

<html data-theme="dark">   <!-- or "light" / omit for light -->

See the Storybook for the full API of every component — props, slots, variants, states, a11y notes.

Visual regression

A small Playwright suite (e2e/visual.spec.ts) takes pixel-level screenshots of a curated set of representative stories — one per component family — in both light and dark themes. Baselines live in e2e/visual.spec.ts-snapshots/ and are committed alongside source changes.

# Run against a locally-served Storybook
npm run build-storybook
npx http-server storybook-static --port 6006 --silent &
npm run test:visual

# Update baselines after an intentional visual change
npm run test:visual:update

CI runs the same suite under the visual-regression job. On a clean PR diffs above maxDiffPixelRatio (1%) fail the build; on the very first run (no committed baselines) CI generates them and uploads as a visual-snapshots artifact for review.

Contributing

See CONTRIBUTING.md for dev-environment setup, coding conventions, how to add a component, and the token workflow.

Development

git clone https://github.com/GregNBlack/kanso-protocol.git
cd kanso-protocol
npm install
npm run build:tokens    # DTCG JSON → CSS / SCSS / TS
npm run storybook       # localhost:6006

Architecture

kanso-protocol/
├── tokens/
│   ├── primitive/        ← Raw values (colors, spacing, sizing)
│   └── semantic/         ← Roles & states (color.primary.default.bg.rest)
├── packages/
│   ├── core/             ← Compiled tokens, types, mixins
│   └── components/
│       └── button/       ← Reference implementation
├── .storybook/           ← Component showcase
└── .github/workflows/    ← CI/CD

Design Tokens

Tokens follow the W3C DTCG specification.

Naming convention:

{category}.{role}.{variant}.{property}.{state}

Example: color.primary.default.bg.hover

Two-level architecture:

Level	Purpose	Example
Primitive	Raw palette values	`color.blue.600` → `#2563EB`
Semantic	Interface roles	`color.primary.default.bg.rest` → `{color.blue.600}`

Component Anatomy

Every component follows a unified three-layer model:

┌─ Container ──────────────────────────┐
│  padding · border · radius · bg      │
│  ┌─ Content ──────────────────────┐  │
│  │  gap                           │  │
│  │  [Element] [Element] [Element] │  │
│  │   icon      label     badge    │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

Full vocabulary, naming rules, and the variant-vs-state model live in docs/component-anatomy.md.

Component Sizes

Size	Height	Radius	Use case
XS	24px	8px	Dense UI, tables, tags
SM	28px	10px	Secondary actions
MD	36px	12px	Default — buttons, inputs
LG	44px	14px	Touch-friendly, primary CTA
XL	52px	16px	Hero actions

States

Six explicit states for every interactive component:

State	Behavior
Rest	Default appearance
Hover	Pointer over element
Active	Pointer pressed
Focus	Keyboard focus — 2px outline ring
Disabled	Action unavailable — removed from tab order
Loading	Action in progress — keeps focus, `aria-busy`

Loading ≠ Disabled. Loading preserves focus and announces state to screen readers.

Usage

import { KpButtonComponent } from '@kanso-protocol/ui/button';

@Component({
  imports: [KpButtonComponent],
  template: `
    <kp-button size="md" variant="default" color="primary">
      Save
    </kp-button>

    <kp-button variant="outline" color="danger" [loading]="isSaving">
      Delete
    </kp-button>
  `,
})
export class MyComponent {
  isSaving = false;
}

Components

41 components, one package. Install once; import each from its own entry point. Tokens live at the package root (@kanso-protocol/ui + @kanso-protocol/ui/styles/*) and load once for any component to render correctly.

npm i @kanso-protocol/ui

Then import only what you use — each entry point is tree-shaken independently:

import { KpButtonComponent } from '@kanso-protocol/ui/button';
import { KpSidebarComponent } from '@kanso-protocol/ui/sidebar';

Every component has a formal API contract (props, variants, states, a11y rules) and a live Storybook page with controls. The Import column below is the entry-point subpath.

Component	Contract	Storybook	Import
Accordion	accordion.md	live ↗	`@kanso-protocol/ui/accordion`
Alert	alert.md	live ↗	`@kanso-protocol/ui/alert`
Avatar	avatar.md	live ↗	`@kanso-protocol/ui/avatar`
AvatarGroup	avatar-group.md	live ↗	`@kanso-protocol/ui/avatar-group`
Badge	badge.md	live ↗	`@kanso-protocol/ui/badge`
Breadcrumbs	breadcrumbs.md	live ↗	`@kanso-protocol/ui/breadcrumbs`
Button	button.md	live ↗	`@kanso-protocol/ui/button`
Card	card.md	live ↗	`@kanso-protocol/ui/card`
Checkbox	checkbox.md	live ↗	`@kanso-protocol/ui/checkbox`
Combobox	combobox.md	live ↗	`@kanso-protocol/ui/combobox`
CommandPalette	command-palette.md	live ↗	`@kanso-protocol/ui/command-palette`
DatePicker	datepicker.md	live ↗	`@kanso-protocol/ui/datepicker`
Dialog	dialog.md	live ↗	`@kanso-protocol/ui/dialog`
Divider	divider.md	live ↗	`@kanso-protocol/ui/divider`
Drawer	drawer.md	live ↗	`@kanso-protocol/ui/drawer`
DropdownMenu	dropdown-menu.md	live ↗	`@kanso-protocol/ui/menu`
EmptyState	empty-state.md	live ↗	`@kanso-protocol/ui/empty-state`
FileUpload	file-upload.md	live ↗	`@kanso-protocol/ui/file-upload`
FormField	form-field.md	live ↗	`@kanso-protocol/ui/form-field`
Icon	icon.md	live ↗	`@kanso-protocol/ui/icon`
Input	input.md	live ↗	`@kanso-protocol/ui/input`
MarkdownViewer	markdown-viewer.md	live ↗	`@kanso-protocol/ui/markdown-viewer`
NumberStepper	number-stepper.md	live ↗	`@kanso-protocol/ui/number-stepper`
Pagination	pagination.md	live ↗	`@kanso-protocol/ui/pagination`
Popover	popover.md	live ↗	`@kanso-protocol/ui/popover`
Progress	progress.md	linear ↗ · circular ↗ · segmented ↗	`@kanso-protocol/ui/progress`
Radio	radio.md	live ↗	`@kanso-protocol/ui/radio`
RichTextEditor	rich-text-editor.md	live ↗	`@kanso-protocol/ui/rich-text-editor`
SegmentedControl	segmented-control.md	live ↗	`@kanso-protocol/ui/segmented-control`
Select	select.md	live ↗	`@kanso-protocol/ui/select`
Skeleton	skeleton.md	live ↗	`@kanso-protocol/ui/skeleton`
Slider	slider.md	live ↗	`@kanso-protocol/ui/slider`
Table	table.md	live ↗	`@kanso-protocol/ui/table`
Tabs	tabs.md	live ↗	`@kanso-protocol/ui/tabs`
Textarea	textarea.md	live ↗	`@kanso-protocol/ui/textarea`
TimePicker	timepicker.md	live ↗	`@kanso-protocol/ui/timepicker`
Toast	toast.md	live ↗	`@kanso-protocol/ui/toast`
Toggle	toggle.md	live ↗	`@kanso-protocol/ui/toggle`
Tooltip	tooltip.md	live ↗	`@kanso-protocol/ui/tooltip`
Tree	tree.md	live ↗	`@kanso-protocol/ui/tree`
VirtualList	virtual-list.md	live ↗	`@kanso-protocol/ui/virtual-list`

Adding a new component? Start from docs/components/_template.md.

Patterns

Patterns are opinionated compositions of components for specific UI use cases. They live in packages/ui/ and are imported the same way as components.

Pattern	What it is	Docs
AppShell	Page chrome — Header + Sidebar + main slot	docs/patterns/app-shell.md
Banner	Full-width announcement strip	docs/patterns/banner.md
Container	Page max-width + padding	docs/patterns/container.md
FilterBar	Active filter chips + add/save/clear	docs/patterns/filter-bar.md
FormSection	Titled block of form fields (inline / stacked)	docs/patterns/form-section.md
Grid	Equal-column responsive grid	docs/patterns/grid.md
Header	Top app bar with logo, nav, search, user	docs/patterns/header.md
NavItem	Single sidebar / nav link with icon and badge	docs/patterns/nav-item.md
NotificationCenter	Bell-anchored notification panel	docs/patterns/notification-center.md
PageError	404 / 500 / generic error page layout	docs/patterns/page-error.md
PageHeader	Title + breadcrumbs + actions + tabs	docs/patterns/page-header.md
Row	Horizontal flex row primitive	docs/patterns/row.md
SearchBar	Inline + command-palette search	docs/patterns/search-bar.md
SettingsPanel	Card of settings rows with controls	docs/patterns/settings-panel.md
Sidebar	Expanded / collapsed app sidebar	docs/patterns/sidebar.md
Stack	Vertical flex stack primitive	docs/patterns/stack.md
StatCard	Single-metric tile for dashboards	docs/patterns/stat-card.md
TableToolbar	Search / filter / actions bar above a table	docs/patterns/table-toolbar.md
ThemeToggle	Light / dark / system switcher	docs/patterns/theme-toggle.md
UserMenu	Avatar + popover with profile + logout	docs/patterns/user-menu.md

Example Pages

Reference page compositions, built only from Kanso components and patterns — no forks, no hand-drawn parts. They live in packages/examples/ (Storybook only, not published to npm) and serve as the integration test for the system.

Page	What it shows	Docs
Login	Centered auth card with form, divider, social buttons	docs/examples/login.md
Dashboard	Full app shell: KPIs, charts, recent activity	docs/examples/dashboard.md
Settings	Tabs + stack of SettingsPanels (Profile / Preferences / Danger zone)	docs/examples/settings.md
List View	Team members table — toolbar, filters, paginated table	docs/examples/list-view.md
Detail View	Project record — rich PageHeader + 2/1 grid of cards	docs/examples/detail-view.md

Templates

Reusable application scaffolds — composed entirely from @kanso-protocol/* components and patterns, but distributed as code, not as npm packages. Drop the file into your project, install peer packages, own the copy. Same convention as Material UI templates, Vercel templates, shadcn-ui.

Why not npm-publish them? Templates are compositions, and every consumer ends up tweaking the layout. Stable layout APIs are hard (one project wants 3 panes, another wants RTL drawer, a third wants a mobile-first stack). Code-as-template lets you take it as a starting point without inheriting our opinions.

Template	What it is	Docs
Workspace	Productivity / admin scaffold — transparent header (logo + flexible header-nav + theme toggle + notifications + user menu), collapsible sidebar with smooth animation, 1-or-2-pane content area with drag-to-resize, light / dark / system theme handling, `prefers-color-scheme` live-tracking. Slot-first API: header-nav / notifications / user-menu items are content-projection slots, so each projected element keeps its own `routerLink` / `(click)` / `*ngIf`.	docs/templates/workspace.md

Quick start (Workspace)

# 1. Install peer packages once (skip the ones you already have):
npm i @kanso-protocol/{core,app-shell,sidebar,nav-item,avatar,user-menu,\
menu,theme-toggle,popover,notification-center,icon,button,badge,breadcrumbs}

# 2. Copy the template file into your project:
mkdir -p src/templates
curl -o src/templates/template-workspace.component.ts \
  https://raw.githubusercontent.com/GregNBlack/kanso-protocol/main/packages/examples/template-modern/template-workspace.component.ts

Then drop it into a route or page component:

import { KpTemplateWorkspaceComponent } from './templates/template-workspace.component';
import {
  KpBreadcrumbsComponent,
  KpBreadcrumbItemComponent,
  KpBreadcrumbSeparatorComponent,
} from '@kanso-protocol/ui/breadcrumbs';
import { KpMenuItemComponent } from '@kanso-protocol/ui/menu';
import { KpIconComponent } from '@kanso-protocol/ui/icon';

@Component({
  standalone: true,
  imports: [
    KpTemplateWorkspaceComponent,
    KpBreadcrumbsComponent,
    KpBreadcrumbItemComponent,
    KpBreadcrumbSeparatorComponent,
    KpMenuItemComponent,
    KpIconComponent,
  ],
  template: `
    <kp-template-workspace
      [navSections]="sections"
      [user]="user"
      [(theme)]="theme"
      (signOut)="logout()">

      <!-- Header-nav slot — breadcrumbs (or a tenant select / tabs / search). -->
      <kp-breadcrumbs kpWsHeaderNav size="md">
        <kp-breadcrumb-item type="link" href="/">Workspace</kp-breadcrumb-item>
        <kp-breadcrumb-separator/>
        <kp-breadcrumb-item type="current">Dashboard</kp-breadcrumb-item>
      </kp-breadcrumbs>

      <!-- User-menu items — each is a real Angular element with own routerLink / click. -->
      <kp-menu-item kpWsUserMenuItems label="Profile"  routerLink="/profile">
        <kp-icon kpMenuItemIcon name="user" size="md"/>
      </kp-menu-item>
      <kp-menu-item kpWsUserMenuItems label="Settings" routerLink="/settings">
        <kp-icon kpMenuItemIcon name="settings" size="md"/>
      </kp-menu-item>

      <div kpWsMain><!-- your main content --></div>
      <div kpWsSide><!-- optional side pane --></div>
    </kp-template-workspace>
  `,
})

Live demo: Storybook → Templates / Workspace. Public API contract: docs/templates/workspace.md.

Figma Integration

The full design library is published on Figma Community — duplicate it into your team to use the components, variables, and example pages directly:

→ Kanso Protocol on Figma Community

Inside: 41 components × variants, 20 patterns, 900+ W3C DTCG variables (light + dark modes), Iconography, and 5 example pages (Login, Dashboard, Settings, List View, Detail View).

Token sync

Tokens stay in lockstep with code via Tokens Studio:

Tokens Studio reads DTCG JSON from this repository
Changes to tokens create a Pull Request
After merge, tokens update in both code and Figma Variables
Components in Figma use Variables — theme switching works automatically

Built with Kanso

Shipping something built on Kanso Protocol? We'd love to feature it here.

Open a PR adding your project to this list, or open an issue with [showcase] in the title and we'll add it for you.

Project	What it is	Link
Be the first.	Open-source app, internal tool, side project — anything counts.	Add yours →

What we ask for: a one-line description, a public link (live URL or GitHub repo), and a single screenshot or short clip.

Guiding Principles

Explicit over implicit. No magic values — everything through tokens.
Architecture over agreements. Rules are structural, not written.
Predictability over flexibility. A small, opinionated API beats a configurable one — every consumer gets the same behavior instead of each team building their own dialect.
Single source of truth. One change, one place.
Every component is equal. Same anatomy, same contract, no exceptions without ADR.

Tech Stack

Framework: Angular 21+
Monorepo: Nx
Tokens: W3C DTCG + Style Dictionary 4 (emits CSS custom properties as the primary runtime, plus equivalent SCSS variables and TS constants for compile-time consumers)
Docs: Storybook 8
Font: Onest (Google Fonts, Cyrillic)
Icons: Tabler Icons
CI/CD: GitHub Actions
Figma sync: Tokens Studio
AI tooling: Model Context Protocol — @kanso-protocol/mcp

Name		Name	Last commit message	Last commit date
Latest commit History 589 Commits
.changeset		.changeset
.github		.github
.husky		.husky
.storybook		.storybook
docs		docs
e2e		e2e
packages		packages
scripts		scripts
tokens		tokens
.gitignore		.gitignore
.mailmap		.mailmap
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
angular.json		angular.json
bundle-budget.json		bundle-budget.json
doctor-storybook.log		doctor-storybook.log
nx.json		nx.json
package-lock.json		package-lock.json
package.json		package.json
style-dictionary.config.js		style-dictionary.config.js
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
tsconfig.spec.json		tsconfig.spec.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

簡素 Kanso Protocol

Why Kanso Protocol?

Live Preview

AI-native: ship with an MCP server

Install

Try it

Install & Use

Visual regression

Contributing

Development

Architecture

Design Tokens

Component Anatomy

Component Sizes

States

Usage

Components

Patterns

Example Pages

Templates

Quick start (Workspace)

Figma Integration

Token sync

Built with Kanso

Guiding Principles

Tech Stack

License

About

Uh oh!

Releases 38

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

簡素 Kanso Protocol

Why Kanso Protocol?

Live Preview

AI-native: ship with an MCP server

Install

Try it

Install & Use

Visual regression

Contributing

Development

Architecture

Design Tokens

Component Anatomy

Component Sizes

States

Usage

Components

Patterns

Example Pages

Templates

Quick start (Workspace)

Figma Integration

Token sync

Built with Kanso

Guiding Principles

Tech Stack

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 38

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages