1Add Sumi to a page

Sumi is a single CSS file with no JavaScript and no build step. Download sumi.min.css, put it next to your HTML file, and link it in the <head>.

Create a file called index.html with this starter:

Open the file in your browser. You should see a centered page with a bold heading, comfortable line spacing and the right colors for your system's light or dark mode.

Use sumi.css instead of the minified file while you learn. It has comments that explain every section.

2Lay out the page

Sumi centers three elements automatically when they are direct children of <body>: <header>, <main> and <footer>. They get a maximum width of 72rem, side padding that adapts to the screen, and sensible vertical spacing. You don't add any classes.

Three classes cover the other layout cases:

3Add navigation

A <nav> with two lists becomes a navigation bar: the first list sits on the left, the second on the right. Mark the current page with aria-current="page". Sumi highlights it, and screen readers announce it.

A link with role="button" looks like a button but still navigates. Use it for calls to action that go to another page or section.

For a breadcrumb trail, label the nav breadcrumb. Sumi adds the separators.

4Write the content

Headings, paragraphs, lists, quotes and code are styled from the element alone. Headings follow a fluid scale, so an <h1> is about 33px on a phone and 45px on a wide screen with no media queries on your side.

Three patterns make a hero section look finished:

• <hgroup> groups a heading with an eyebrow (<h6>) above it and a subtitle (<p>) below it.
• .lead makes an intro paragraph larger.
• .display makes a headline larger still, for a landing page.

Long-form text

For an article or a blog post, wrap the text in .prose. It limits lines to about 68 characters, increases the line spacing slightly and turns on hyphenation. Add .serif to switch to a serif typeface, which many readers find calmer for long texts.

An <article> normally becomes a card (step 6). With .prose it stays plain text, because a long article should not sit in a box.

5Arrange content in a grid

.grid places its children in as many columns as fit, each at least 14rem wide. On a phone they stack into one column. You don't set any breakpoints.

When you need exact columns, add .cols-2, .cols-3, .cols-4, .cols-6 or .cols-12. These apply from 48rem (768px) upwards; below that the grid is a single column. In a 12-column grid, children can take .span-2 to .span-9, or .span-full for a whole row.

For a single row of items, use .row (a wrapping flex row with a gap). Add .spread to push items to both ends. .stack is the vertical version.

6Show options in cards

Every <article> is a card. If the article starts with a <header> or ends with a <footer>, those become shaded bands across its full width. Put cards in a grid and they line up.

.full stretches a button across its container. Buttons come in .secondary and .contrast colors, an .outline style, and .small and .large sizes. You can combine them, as in class="secondary outline small".

7Build a booking form

Form fields need no classes. Wrap each field in its <label> and it gets full width, padding and a focus ring. A <small> placed right after a field becomes helper text.

Try submitting the empty form. Fields turn red because a small script sets aria-invalid="true" on them. Sumi styles that attribute, and screen readers announce it too. Valid fields get aria-invalid="false" and turn green.

Two more patterns are worth knowing:

• <input type="checkbox" role="switch"> draws a toggle switch instead of a checkbox.
• <div role="group"> joins an input and a button into one control, like a search bar.

8Add interactive parts

Sumi styles the browser's own interactive elements, so most of these work with no JavaScript.

FAQ accordion

Each <details> opens and closes on click. Add open to start one expanded.

Dropdown menu

Add class="dropdown" to a <details> and put a list inside. Add .right as well to align the menu to the right edge.

Modal dialog

Put an <article> inside a <dialog>. Opening a modal needs one line of JavaScript, dialog.showModal(). Closing does not: a button inside <form method="dialog"> closes it, and so does the Esc key.

Tooltips, loading and messages

Three attributes and one class cover the remaining feedback you'll need.

• data-tooltip="…" shows a tooltip on hover and keyboard focus. Add data-placement="bottom" to show it below.
• aria-busy="true" adds a spinner to any element. Remove the attribute when loading finishes.
• .callout is a message box. Add .success, .warning or .danger for the color.

9Make it yours

Every color, font, size and radius in Sumi is a CSS custom property that starts with --s-. To rebrand the whole site, put your own values in a stylesheet that loads after Sumi:

Custom properties also work on a single element. These buttons use the same classes as before. Only the parent's style attribute changes them:

Fonts

Sumi uses each system's own interface font by default, so pages load with no font downloads. To use a web font, load it as usual and point a token at it. --s-font-body sets the text, and --s-font-heading sets the headings (it follows the body font unless you set it).

Dark mode

Dark mode is already on. Sumi follows the visitor's system setting. To force a mode, set data-theme on the <html> element:

A theme switch is a few lines of JavaScript. This one remembers the visitor's choice:

data-theme also works on any element, so one section can be dark inside a light page:

The dark palette is defined twice in sumi.css: once for the system setting and once for data-theme="dark". If you change dark colors, change both blocks.

10Add your own CSS

Most of Sumi's element styles sit inside :where(), which gives them zero specificity. Any selector you write wins, without !important and without long selector chains.

Build new components from Sumi's tokens, as the badge above does. They then follow dark mode and your brand colors automatically. The tokens you'll use most are --s-text, --s-muted, --s-bg, --s-surface, --s-border, --s-primary and --s-radius.

To turn off a default for one element, override it with a class. For example, an <article> that should not be a card:

✓The finished page

Here are the pieces put together into one page. The full source is under the preview, ready to copy into index.html.

Cheat sheet

Every class and attribute Sumi responds to. Everything else is plain HTML.

Browser support

Sumi works in current versions of Chrome, Edge, Firefox and Safari. It relies on :where(), :has() and color-mix(), which are available from Chrome and Edge 111, Firefox 121 and Safari 16.2. Older browsers still show readable pages, with plainer hover and focus colors.