Sensible UI

v1.7.0beta

Build shadcn/ui-inspired components with plain HTML and one stylesheet. Start with polished defaults, then make them your own with CSS variables. No Tailwind, JavaScript framework, or build step required.

Getting started

Add one stylesheet to your HTML page. Buttons, form controls, typography, and tables get shadcn/ui-inspired styles by default. The core is CSS-only: no JavaScript or npm install needed.

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

Write semantic HTML and the stylesheet handles the look. Native elements do not need component classes. Serve your page over HTTP, including when you test locally. Keep the URL pinned to a release and change the version when you want to update.

Get in touch

Send a message and we will reply by email.

<section>
  <h1>Get in touch</h1>
  <p>Send a message and we will reply by email.</p>
  <form>
    <label for="example-email">Email</label>
    <input id="example-email" name="email" type="email">
    <button type="button">Send message</button>
  </form>
</section>

To add a component, copy an example below. Use named classes such as class="card" for patterns without a native HTML element, and attributes such as data-variant="outline" to choose a style. Override CSS variables such as --primary, --primary-foreground, and --radius to change colors and rounded corners. Optional JavaScript adds behavior such as syntax highlighting and code copying.

If you use a bundler, install @faith-tools/sensible-ui and import the complete stylesheet in your CSS:

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

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`, `/dialog`, `/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

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>

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>

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>

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>

Dialog

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

A native dialog opens modally with showModal() or non-modally with show(). The standalone dialog import includes button styles; import /input separately for form controls. JavaScript only connects your trigger to the native method; no component runtime is required. Do not set open directly to create a modal.

Identify the dialog with aria-labelledby and add aria-describedby for a short description. Direct header, section, and footer children provide the title, scrollable content, and actions. Provide a visible close control. A form method="dialog" closes without submitting data; handle saving in your application and close only after it succeeds. Choose initial focus with autofocus when needed.

<button type="button" onclick="document.getElementById('project-dialog').showModal()">View project</button>
<dialog id="project-dialog" aria-labelledby="project-title" aria-describedby="project-description">
  <header>
    <h2 id="project-title">Project details</h2>
    <p id="project-description">A quick look at your project.</p>
    <form method="dialog">
      <button type="submit" value="close" data-variant="ghost" data-size="icon" aria-label="Close" autofocus>×</button>
    </form>
  </header>
  <section><p>Website redesign is ready for review.</p></section>
  <footer>
    <form method="dialog"><button type="submit" value="done">Done</button></form>
  </footer>
</dialog>

Optional backdrop dismissal

Modal dialogs close with Escape by default, but a backdrop click does not dismiss them. Add closedby="any" only when discarding the dialog is safe. Keep a visible close control for browsers that do not support closedby.

<button type="button" onclick="document.getElementById('tip-dialog').showModal()">Show tip</button>
<dialog id="tip-dialog" closedby="any" aria-labelledby="tip-title">
  <header>
    <h2 id="tip-title">A quick tip</h2>
    <form method="dialog"><button type="submit" value="close" data-variant="ghost" data-size="icon" aria-label="Close" autofocus>×</button></form>
  </header>
  <section><p>Click outside this dialog, press Escape, or select Close.</p></section>
</dialog>

Long content

The content region scrolls while the header and actions stay visible. On short viewports, the whole dialog scrolls so the body remains readable. The same layout works in dark mode and at narrow widths.

<button type="button" onclick="document.getElementById('long-dialog').showModal()">Read project notes</button>
<dialog id="long-dialog" aria-labelledby="long-title" aria-describedby="long-description">
  <header>
    <h2 id="long-title">Project notes</h2>
    <p id="long-description">Review the notes before continuing.</p>
    <form method="dialog"><button type="submit" value="close" data-variant="ghost" data-size="icon" aria-label="Close">×</button></form>
  </header>
  <section>
    <p>Start with the goals and the people the project serves.</p>
    <p>Check the scope, timeline, and remaining questions.</p>
    <p>Record feedback from the team and assign follow-up work.</p>
    <p>Review the revised design with stakeholders.</p>
    <p>Confirm the final content and accessibility checks.</p>
    <p>Prepare the handoff notes and the release checklist.</p>
    <p>Keep decisions and open questions together for reference.</p>
  </section>
  <footer><form method="dialog"><button type="submit" value="done">Done</button></form></footer>
</dialog>

Non-modal

show() leaves the page interactive and has no backdrop or automatic Escape dismissal. Always include an explicit close control. Use a modal when the task requires focus to stay inside the dialog.

<button type="button" onclick="document.getElementById('note-dialog').show()">Open note</button>
<dialog id="note-dialog" aria-labelledby="note-title">
  <header>
    <h2 id="note-title">Quick note</h2>
    <form method="dialog"><button type="submit" value="close" data-variant="ghost" data-size="icon" aria-label="Close" autofocus>×</button></form>
  </header>
  <section><p>You can still use the rest of the page.</p></section>
</dialog>

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>

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>

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>

Container

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

Add class="container" to center content and limit its width. It fills the available width up to 640px by default, with 1rem of padding on all sides. At viewport widths of 40rem and above, the padding becomes 1.5rem. The core bundle includes this class; no companion stylesheet is needed.

Set --container-width on the container to choose a different maximum width. The example uses 32rem. The class works on main, section, or div; a plain main does not get container styles automatically. .page is an alias for .container.

Centered content

Keep content readable without stretching across the whole page.

<div class="container" style="--container-width: 32rem">
  <h3>Centered content</h3>
  <p>Keep content readable without stretching across the whole page.</p>
</div>

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>

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>

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.

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

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

If you use a bundler, import the scoped bundle in your CSS instead of using the CDN link:

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

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.

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>

Add highlighted code

Add the optional stylesheet and browser module to pages that need syntax highlighting. The component works without the main Sensible UI stylesheet. Serve the page over HTTP so the browser can load the module.

Add the component styles to your HTML:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@faith-tools/sensible-ui@1.7.0/src/css/code.css">
Load the component as a browser module:
<script type="module" src="https://cdn.jsdelivr.net/npm/@faith-tools/sensible-ui@1.7.0/dist/sensible-code.js"></script>
Add sensible-code with a read-only textarea containing the source:
<sensible-code language="html" data-wrap="true"> <textarea readonly><button>Save</button></textarea> </sensible-code>

If you use a bundler, install @faith-tools/sensible-ui. Import the styles in your CSS and the component in your browser JavaScript instead of using the CDN tags:

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

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

The code below shows syntax colors, a Wrap lines toggle, and a Copy button. Code scrolls horizontally by default at every screen width. Set data-wrap="true" to start a block wrapped. Readers can switch either block between wrapping and scrolling. 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>

<a href="/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/a/long/example/path/">Read the example</a>