Sensible UI

v1.6.0beta

A semantic-first CSS component library with shadcn-style visual defaults.

Getting started

Import the complete stylesheet when you want every semantic default and component:

@import '@faith-tools/sensible-ui';

Or use the versioned CDN build:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@faith-tools/sensible-ui@1.6.0/dist/sensible-ui.min.css">

Standalone component imports include the theme and base styles they need. When markup combines components, import each component. For example, <table class="card"> needs both /table and /card.

All public stylesheet exports

Export	Purpose
`.`, `/css`	Complete bundled stylesheet
`/min`	Minified complete bundle
`/index`	Source CSS entry point
`/base`	Theme tokens and semantic reset
`/theme`	Theme tokens and cascade layer order
`/accordion`, `/badge`, `/button`, `/card`	Standalone component modules
`/code/css`	Optional code component styles; JavaScript is under `/code`
`/description-list`, `/image`, `/input`, `/item`	Standalone component modules
`/spinner`, `/table`, `/typography`	Standalone component modules
`/utils`	Named layouts, container, and composition helpers
`/utilities`, `/utilities/min`	Optional generated atomic utilities
`/view-transition`	Optional same-origin page transitions

Limit styles to part of a page

Use the scoped bundle when adding Sensible UI to an existing application. Semantic defaults apply only inside a neutral .sensible-ui wrapper, leaving the rest of the page alone.

@import '@faith-tools/sensible-ui/scoped';

<section class="sensible-ui">
  <h2>Account settings</h2>
  <label for="display-name">Display name</label>
  <input id="display-name">
  <button>Save changes</button>
</section>

Put the class on a wrapper, not on a card, table, link, or form control. Sensible UI layout and utility classes such as .stack, .mt-4, and .size-8 also belong on descendants, not the scope root. You can combine the scope class with a host-owned wrapper class. Scoped component and utility imports use the same names under /scoped, such as /scoped/button and /scoped/utilities. Scoped mode requires browser support for @scope.

View the scoped bundle beside host styles.

Typography

Standalone import: @import '@faith-tools/sensible-ui/typography';

Headings, paragraphs, links, lists, code, keyboard input, quotations, and inline text semantics are styled without classes. Keep the native element that matches the content’s meaning.

Geist and Geist Mono are optional. The stylesheet prefers them but does not load them, so your system fonts are used unless you provide the fonts separately. See the font setup in the README for HTML and Next.js examples, or override --font-sans and --font-mono to use your own fonts.

A clear heading

Use semantic HTML for meaning and emphasis.

Good defaults should support the content.

Press Ctrl + K to search.

const greeting = "Hello";

<article>
  <h1>A clear heading</h1>
  <p>Use <strong>semantic HTML</strong> for meaning and <em>emphasis</em>.</p>
  <blockquote>Good defaults should support the content.</blockquote>
  <p>Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to search.</p>
  <pre><code>const greeting = "Hello";</code></pre>
</article>

Add highlighted code

If your project uses a bundler, import the optional stylesheet and browser module. The default Sensible UI stylesheet does not include either one. If you have not installed the package, run npm install @faith-tools/sensible-ui first.

Import the component styles in your CSS entry:
@import '@faith-tools/sensible-ui/code/css';
Import the component in your browser JavaScript entry:
import '@faith-tools/sensible-ui/code';
Add sensible-code with a read-only textarea containing the source:
<sensible-code language="html"> <textarea readonly><button>Save</button></textarea> </sensible-code>

The code below shows syntax colors and a Copy button. Without JavaScript, the read-only text area remains readable. The component creates pre and code when it loads. In HTML source, escape & before entity names. If the example contains </textarea>, write its opening angle bracket as <. Set language to a supported language name, such as html, css, or python.

<button type="button">Save</button>
<p>Ready & waiting</p>

Buttons

Standalone import: @import '@faith-tools/sensible-ui/button';

Native buttons, button-like inputs, and a.button are supported. Use data-variant for primary, secondary, outline, ghost, link, or destructive treatment. Use data-size for sm, lg, or icon. Native disabled, aria-pressed, aria-busy, and aria-invalid attributes style state.

Use a button for actions and a link for navigation. Give icon-only buttons an accessible name.

Link as button

<div class="cluster">
  <button type="button">Primary</button>
  <button type="button" data-variant="secondary">Secondary</button>
  <button type="button" data-variant="outline">Outline</button>
  <button type="button" data-variant="ghost">Ghost</button>
  <button type="button" data-variant="link">Link</button>
  <button type="button" data-variant="destructive">Destructive</button>
  <button type="button" data-size="sm">Small</button>
  <button type="button" data-size="lg">Large</button>
  <button type="button" aria-pressed="true">Pressed</button>
  <button type="button" disabled>Disabled</button>
  <a class="button" href="#buttons">Link as button</a>
</div>

Form controls

Standalone import: @import '@faith-tools/sensible-ui/input';

The input module styles native controls and their labels. Associate every control with a label. Use fieldset andlegend for related choices, and use aria-describedby when an error or hint needs to be announced.

Text-like inputs and states

Text, email, password, number, search, URL, and similar inputs share the same semantic default.

Account ID

Email with an error Enter a valid email address.

Disabled input

<div class="stack">
  <div>
    <label for="profile-email">Email</label>
    <input id="profile-email" name="email" type="email" placeholder="name@example.com">
  </div>
  <div>
    <label for="profile-id">Account ID</label>
    <input id="profile-id" name="id" value="04D6H89Z" readonly>
  </div>
  <div>
    <label for="invalid-email">Email with an error</label>
    <input id="invalid-email" type="email" aria-invalid="true" aria-describedby="email-error">
    <small id="email-error">Enter a valid email address.</small>
  </div>
  <div>
    <label for="disabled-input">Disabled input</label>
    <input id="disabled-input" disabled value="Unavailable">
  </div>
</div>

Textarea

About

<div>
  <label for="profile-about">About</label>
  <textarea id="profile-about" name="about" placeholder="Tell us about yourself"></textarea>
</div>

Select

Use the native select when choosing one option from a list. Group long option lists with optgroup.

Time zone

<div>
  <label for="timezone">Time zone</label>
  <select id="timezone" name="timezone">
    <option value="">Choose a time zone</option>
    <optgroup label="North America">
      <option value="America/Chicago">Central Time</option>
      <option value="America/New_York">Eastern Time</option>
    </optgroup>
  </select>
</div>

Checkbox

Use checkboxes for independent choices. The checked and disabled states are native.

Notifications

Product updates

Security alerts

<fieldset>
  <legend>Notifications</legend>
  <div>
    <input id="product-updates" type="checkbox" name="updates" checked>
    <label for="product-updates">Product updates</label>
  </div>
  <div>
    <input id="security-alerts" type="checkbox" name="security" disabled>
    <label for="security-alerts">Security alerts</label>
  </div>
</fieldset>

Radio group

Radio buttons with the same name represent one choice. Wrap the group in a fieldset with a legend.

Contact preference

Phone

<fieldset>
  <legend>Contact preference</legend>
  <div>
    <input id="contact-email" type="radio" name="contact" value="email" checked>
    <label for="contact-email">Email</label>
  </div>
  <div>
    <input id="contact-phone" type="radio" name="contact" value="phone">
    <label for="contact-phone">Phone</label>
  </div>
</fieldset>

Switch

Add role="switch" to a checkbox only when the control immediately turns a setting on or off.

Marketing emails

<label>
  <input type="checkbox" role="switch" name="marketing" checked>
  Marketing emails
</label>

Range

Provide a visible label and meaningful minimum, maximum, and initial values.

Volume

<div>
  <label for="volume">Volume</label>
  <input id="volume" name="volume" type="range" min="0" max="100" value="65">
</div>

Date and time

Date and datetime-local inputs preserve each browser’s native picker and keyboard behavior.

Start date

Appointment

<div class="auto-grid" style="--min-item-size: 12rem">
  <div>
    <label for="start-date">Start date</label>
    <input id="start-date" name="start-date" type="date">
  </div>
  <div>
    <label for="appointment">Appointment</label>
    <input id="appointment" name="appointment" type="datetime-local">
  </div>
</div>

Color

Accent color

<label>
  <input name="accent" type="color" value="#2563eb">
  Accent color
</label>

File

Use the accept attribute as a picker hint, not as file validation.

Profile image

<div>
  <label for="avatar-file">Profile image</label>
  <input id="avatar-file" name="avatar" type="file" accept="image/*">
</div>

Card

Standalone import: @import '@faith-tools/sensible-ui/card';

Add class="card" to a semantic container. Direct header, section, and footer children define its regions. Add data-slot="card-action" to a header action. Cards adapt their layout through container queries.

Team plan

For growing organizations

Invite collaborators and share project settings.

<article class="card">
  <header>
    <h3>Team plan</h3>
    <p>For growing organizations</p>
    <button type="button" data-slot="card-action" data-variant="outline">Manage</button>
  </header>
  <section>
    <p>Invite collaborators and share project settings.</p>
  </section>
  <footer>
    <button type="button">Choose plan</button>
    <button type="button" data-variant="outline">Learn more</button>
  </footer>
</article>

Badge

Standalone import: @import '@faith-tools/sensible-ui/badge';

Add class="badge" to short status or category text. Supported variants are primary, secondary, outline, and destructive. Use a link only when the badge navigates somewhere. aria-invalid="true" provides the invalid state.

Default Secondary Outline Destructive Linked badge

<div class="cluster">
  <span class="badge">Default</span>
  <span class="badge" data-variant="secondary">Secondary</span>
  <span class="badge" data-variant="outline">Outline</span>
  <span class="badge" data-variant="destructive">Destructive</span>
  <a class="badge" data-variant="outline" href="#badges">Linked badge</a>
</div>

Image

Standalone import: @import '@faith-tools/sensible-ui/image';

Images receive responsive sizing and rounded corners. Use an empty alt value for decorative images and useful alternative text for informative images. Pair an image and caption with figure and figcaption.

A mountain ridge beneath a cloudy sky — Images and captions receive sensible defaults.

<figure>
  <img
    src="https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?auto=format&fit=crop&w=960&q=80"
    alt="A mountain ridge beneath a cloudy sky"
    width="960"
    height="540"
  >
  <figcaption>Images and captions receive sensible defaults.</figcaption>
</figure>

Item

Standalone import: @import '@faith-tools/sensible-ui/item';

An item is a compact content row with an optional icon or action. Use a.item when the entire row navigates. Do not put another interactive control inside a linked item.

Project settings

Manage members, billing, and notifications.

Linked item

The whole row is one descriptive link.

<div class="stack">
  <div class="item">
    <section>
      <h3>Project settings</h3>
      <p>Manage members, billing, and notifications.</p>
    </section>
    <button type="button" data-variant="outline">Open</button>
  </div>
  <a class="item" href="#item">
    <section>
      <h3>Linked item</h3>
      <p>The whole row is one descriptive link.</p>
    </section>
    <span aria-hidden="true">→</span>
  </a>
</div>

Loading spinner

Standalone import: @import '@faith-tools/sensible-ui/spinner';

Add aria-busy="true" while an element is updating. Add data-variant="overlay" to dim existing children. Keep visible loading text or an accessible name so the state is understandable without relying on motion.

Loading report

The current content remains visible while loading.

<div class="stack">
  <button type="button" aria-busy="true" disabled>Saving</button>
  <div class="card" aria-busy="true" data-variant="overlay">
    <header><h3>Loading report</h3></header>
    <section><p>The current content remains visible while loading.</p></section>
  </div>
</div>

Accordion

Standalone import: @import '@faith-tools/sensible-ui/accordion';

Native details and summary provide disclosure behavior without JavaScript. The open attribute sets the initial state. Give related details elements the same name when only one should remain open.

Does this require JavaScript?

No. It uses the native details and summary elements.

Can only one item stay open?

Yes. Give related details elements the same name.

<div>
  <details name="questions">
    <summary>Does this require JavaScript?</summary>
    <p>No. It uses the native details and summary elements.</p>
  </details>
  <details name="questions" open>
    <summary>Can only one item stay open?</summary>
    <p>Yes. Give related details elements the same name.</p>
  </details>
</div>

Description list

Standalone import: @import '@faith-tools/sensible-ui/description-list';

Use a description list for name-value groups, terms and definitions, or metadata. Multiple terms may share a description and one term may have multiple descriptions. Add class="card" and import the card module for the bordered treatment.

Status: Active
Plan: Team
Renewal date: January 15, 2027

<dl class="card">
  <dt>Status</dt>
  <dd>Active</dd>
  <dt>Plan</dt>
  <dd>Team</dd>
  <dt>Renewal date</dt>
  <dd><time datetime="2027-01-15">January 15, 2027</time></dd>
</dl>

Table

Standalone import: @import '@faith-tools/sensible-ui/table';

Use tables for two-dimensional data. Add a caption when the surrounding context does not already identify the table, and usescope on row and column headers. Add class="card" and import the card module for the bordered treatment.

Current project members
Name	Role	Status
Margaret Nguyen	Owner	Active
Hoshi Nakamura	Editor	Invited
Total		2

<table class="card">
  <caption>Current project members</caption>
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Role</th>
      <th scope="col">Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Margaret Nguyen</th>
      <td>Owner</td>
      <td>Active</td>
    </tr>
    <tr>
      <th scope="row">Hoshi Nakamura</th>
      <td>Editor</td>
      <td>Invited</td>
    </tr>
  </tbody>
  <tfoot>
    <tr><th scope="row" colspan="2">Total</th><td>2</td></tr>
  </tfoot>
</table>

Named layouts

Standalone import: @import '@faith-tools/sensible-ui/utils';

The core bundle includes .stack for vertical flow, .cluster for wrapping inline groups, .split for separated content, and .auto-grid for intrinsic grids. .y-stack aliases stack and .x-stack is a non-wrapping inline stack. Set --layout-gap to adjust spacing and --min-item-size to control grid wrapping.

Cluster Wraps inline content

Split layout

First

Second

Third

<div class="stack">
  <div class="cluster">
    <span class="badge">Cluster</span>
    <span class="badge" data-variant="secondary">Wraps inline content</span>
  </div>
  <div class="split">
    <strong>Split layout</strong>
    <button type="button" data-size="sm">Action</button>
  </div>
  <div class="auto-grid" style="--min-item-size: 10rem">
    <div class="card"><section>First</section></div>
    <div class="card"><section>Second</section></div>
    <div class="card"><section>Third</section></div>
  </div>
</div>

Optional atomic utilities

Optional import: @import '@faith-tools/sensible-ui/utilities';

The companion stylesheet provides token-backed display, flex, grid, alignment, sizing, spacing, positioning, overflow, text, aspect-ratio, and accessibility helpers. It is plain generated CSS and requires no template scanning or consumer-side tooling. Override the --space-* custom properties to change its spacing scale. Prefer named helpers such as .stack, .y-stack, and .x-stack for common composition, then use atomic helpers for exceptions. Breakpoint-prefixed variants are intentionally not generated; use intrinsic layouts or consumer-owned media queries instead.

1:1

Utility example

A long status message is truncated with an ellipsis when the available inline space is limited, preserving a compact row without wrapping into the content below or pushing neighboring controls out of view.

<div class="x-stack">
  <div class="card relative w-16 shrink-0 aspect-square overflow-hidden">
    <span class="absolute inset-0 flex items-center justify-center">1:1</span>
  </div>
  <div class="y-stack min-w-0 grow shrink" style="--layout-gap: var(--space-1)">
    <span class="sr-only">Status:</span>
    <strong>Utility example</strong>
    <p class="truncate">A long status message is truncated with an ellipsis when the available inline space is limited, preserving a compact row without wrapping into the content below or pushing neighboring controls out of view.</p>
  </div>
</div>

Dark mode

Add class="dark" to an ancestor to select the bundled dark theme. Components use the same markup in both themes. System preference behavior is not enabled by the core bundle.

Dark card

The same semantic markup works.

Dark theme

<div class="auto-grid" style="--min-item-size: 12rem">
  <article class="card">
    <header><h3>Dark card</h3><p>The same semantic markup works.</p></header>
    <section><span class="badge" data-variant="secondary">Dark theme</span></section>
  </article>
  <form>
    <div>
      <label for="dark-email">Email</label>
      <input id="dark-email" type="email" placeholder="name@example.com">
    </div>
    <button type="button">Continue</button>
  </form>
</div>