Design guidelines

#Drawers

• Fit the content. A drawer is as tall as what is in it, with no empty space at the bottom. Don’t pad it to look bigger, and don’t set a height on your popup page.
• Lead with this page. Put what matters on the current site first: a header switch “On for news.example”, then the controls.
• Keep it short. If people must scroll the drawer, move things to your settings page.
• One primary action. At most one black button. Others are outlined or rows.
• Answer popup.opening within 400 ms with what you already know. Fill in slow numbers later with another popup.set.
• On Home and Pulsar’s pages (host is null) say what to do: “Open a page to use it”.

#Colour

• Black is the primary colour (white in dark mode): main buttons, switches that are on, chosen chips.
• Green `#10A37F` only for success and active details: a “Saved” badge, a running dot, a finished ring. Never for buttons.
• Red only for danger: remove, clear, delete. Amber warns, blue informs.
• Your tint colours your tile and media cards. Keep it out of the rest of the UI.
• No gradients, no shadows. Separate things with a 1 px hairline (--pl-hair) or the ground colour.

#Spacing and shape

#Typography

Inter, falling back to the phone’s font. Respect the user’s text size: use the kit’s classes, or rem and em, never fixed heights on text.

• Sentence case everywhere: “Block ads”, not “Block Ads”.
• Numbers that change use tabular figures (font-variant-numeric: tabular-nums, built into the kit’s stats).

#Motion

Things move only to explain what changed. Pulsar animates transform and opacity only, and lands on exact end states.

• Standard cubic-bezier(.4, 0, .2, 1) for things that move. Decelerate (0, 0, .2, 1) for things that enter. Accelerate (.4, 0, 1, 1) for things that leave.
• New things rise 8 px while they fade in. Groups appear 20 ms apart, the 6th and later together.
• Honour reduced motion: things appear at once, and spinners become a soft pulsing dot. The kit does this for you.

#Dark mode

• Every screen must work in both. Pulsar draws native specs in both by itself; the kit follows the phone.
• In dark mode the primary is white with black text. Don’t hard-code #000 or #FFF: use the tokens.
• Pictures you draw (swatches, previews) keep their own colours and get a hairline so they show on both grounds.
• Test with the phone in dark mode, not only by flipping data-theme.

#Touch targets

• Everything tappable is at least 48 × 48 px. Small buttons and icon buttons in the kit keep a 48 px touch area around them.
• Put switches and checkboxes inside a <label> row so the whole row is the target.
• Keep 8 px between targets. Don’t put two tappable things in one row unless one is the row itself.
• Primary actions sit where thumbs reach: at the bottom of drawers and sheets.

#Accessibility

• Native specs are accessible for free: TalkBack reads titles, values and states.
• In HTML, use real <button>, <a>, <label> and <input>. Give icon buttons an aria-label.
• Keep text contrast at 4.5:1 or more. The kit’s ink, mut and red pass on card and ground in both themes; faint is for hints only.
• Never show state with colour alone: a switch moves, a chosen chip turns black, a badge has a word.
• Keep focus visible (the kit draws a 2 px ink ring). Sheets, menus and dialogs keep focus inside and give it back when they close.
• Test with TalkBack and with the largest font size.

#Writing

Short plain words, like you would say them. People read drawers in a second.

• Buttons say what they do: “Remove”, “Save list”, not “OK” or “Yes”.
• Name things the way Pulsar does: extensions, sites, tabs, settings.
• No exclamation marks, no jokes in errors, no “please”.
• Write numbers as digits: “3 sites”, “12 MB”.