Tangible UI

Design system for Tangible WordPress plugins. React components, CSS custom property tokens, and CSS-only form elements.

Live Storybook: https://storybook-tangible-ui.pages.dev

Components

• Primitives: Button, IconButton, Chip, ChipGroup, Icon, Progress, Rating, Tooltip
• Layout: Accordion, Card, Modal, Notice, Sidebar, Tabs, Toolbar
• Data: DataTable, StepList, StepIndicator, Pager
• Form Controls: Select, MultiSelect, Combobox, TextInput, Textarea, Checkbox, Switch, Radio/RadioGroup
• Composites: Avatar, Dropdown, MoveHandle, OverlapStack, SegmentedControl, Field
• CSS-only Inputs: Text, textarea, select, checkbox, radio, toggle, file (no JS required)

Getting Started

Install

npm install @tangible/ui

Optional peer dependencies

Some components require additional packages. Install only what you use:

| Package | Required by | Size | |---------|-------------|------| | @floating-ui/react | Select, MultiSelect, Combobox, Dropdown, Tooltip, Popover | ~90 KB | | @tanstack/react-table | DataTable | ~50 KB |

# If using Select, Dropdown, Tooltip, etc.
npm install @floating-ui/react

# If using DataTable
npm install @tanstack/react-table

Components without these dependencies (Button, Card, Accordion, Modal, Tabs, etc.) work with zero additional installs.

Import styles

The prebuilt stylesheet ships every component:

import '@tangible/ui/styles';

For WordPress plugin contexts where CSS layers can lose to unlayered theme styles:

import '@tangible/ui/styles/unlayered';

Prebuilt core-only builds (tokens, resets, utilities, icon — no components) are available as @tangible/ui/styles/core and @tangible/ui/styles/core.unlayered.

Compiling a subset

If your build compiles Sass, you can ship only the components you use — a typical five-component subset weighs ~63 KB instead of the full ~200 KB:

// tui-subset.scss
@use "@tangible/ui/styles/index" with (
  $components: (button, checkbox, radio, notice, modal),
  $layers: false // flat output for WordPress-style unlayered hosts
);

Notes:

• Component keys are the kebab-case component names (button, text-input, icon-button, chip-group, …).
• Core tokens, resets, utilities, and icon styles always emit.
• The shared input-core styles are pulled in automatically when any of field, text-input, textarea, or pager is requested (or request them directly with input).
• Omit $layers: false to keep the cascade-layer organisation (resets, components, utilities).

Set up the interface wrapper

All components require the .tui-interface wrapper to access design tokens:

function App() {
  return (
    <div className="tui-interface">
      {/* Your UI here */}
    </div>
  );
}

Dark mode

Set data-theme on the wrapper:

<div className="tui-interface" data-theme="dark">

• "dark" — force dark mode
• "auto" — follow prefers-color-scheme
• Omit attribute — light mode (inherits host colour)

Use components

import { Button, Card, Select, SelectOption } from '@tangible/ui';

function Example() {
  return (
    <Card>
      <Card.Body>
        <Button label="Save" theme="primary" />

        <Select placeholder="Choose..." onValueChange={(v) => console.log(v)}>
          <Select.Trigger />
          <Select.Content>
            <Select.Option value="a">Option A</Select.Option>
            <Select.Option value="b">Option B</Select.Option>
          </Select.Content>
        </Select>
      </Card.Body>
    </Card>
  );
}

Tree-shaking

Individual component imports are available if your bundler doesn't tree-shake the barrel export:

import { Button } from '@tangible/ui/components/Button';
import { Tooltip } from '@tangible/ui/components/Tooltip';

Customisation

Token overrides

Components are styled via CSS custom properties. Override them on .tui-interface or any ancestor:

/* Global overrides */
.tui-interface {
  --tui-radius-md: 2px;
  --tui-focus-ring-color: hotpink;
}

/* Scoped to a specific context */
.my-sidebar .tui-interface {
  --tui-button-radius: 0;
  --tui-control-height-md: 32px;
}

Component API tokens

Each component reads its own --tui-{component}-* tokens via fallback chains. These are never defined by TUI — only read. Set them from consuming code:

.compact-form {
  --tui-accordion-padding: 8px;
  --tui-select-trigger-radius: 2px;
  --tui-modal-spacing: 24px;
}

See each component's styles.scss header for its full token API.

Form control sizing

All form controls share a unified sizing system:

.my-context .tui-interface {
  --tui-control-height-sm: 28px;
  --tui-control-height-md: 32px;
  --tui-control-height-lg: 40px;

  /* Optional: decouple font size from size tier */
  --tui-control-font-size-sm: 13px;
  --tui-control-font-size-md: 13px;
  --tui-control-font-size-lg: 14px;
}

Icons

Four icon sets available via the registry: system, cred, reaction, player.

import { Icon } from '@tangible/ui';

<Icon name="system/check" />
<Icon name="reaction/clap-fill" size="lg" />

Development

npm install
npm run storybook   # Dev server on port 6006

Commands

npm run storybook          # Dev server
npm run build:lib          # Build library (outputs to publish/)
npm run lint               # ESLint
npm run test               # Unit tests (vitest, jsdom)
npm run test:storybook     # Story + a11y tests (vitest, Playwright chromium)
npm run test:visual        # Visual regression (Playwright)
npm run test:visual:update # Regenerate visual baselines

Documentation

• CONTRIBUTING.md — The pattern language: how components are built here
• CLAUDE.md — Architecture, patterns, conventions, gotchas
• CONTEXT.md — Project background and design philosophy
• TIMELINE.md — Development roadmap
• TESTING.md — Testing strategy and infrastructure
• CHANGELOG.md — Release history

Status

Under active development. Component APIs are stabilising but may change before 1.0.