Good Css

Good CSS

One declaration that adapts on its own beats a set of breakpoints, and a CSS feature beats a script. Use JavaScript only where it makes a result nicer that already works without it.

Each technique is a set of properties and values, so it works in any authoring system. Class names in the examples are placeholders. Write the declarations in what the project already uses, whether that is a stylesheet, Tailwind utilities or StyleX objects. Where that system has no shorthand for a declaration, write it the long way, as a Tailwind arbitrary property or a rule in the project's CSS file. Do not swap the technique for a breakpoint.

In all CSS

These need no file.

• Write inline and block properties in place of left, right, top and bottom. Tailwind has them too, as in mbs-, pe- and inset-bs-, so never write mt-, pr- or top-. The block ones need Tailwind 4.2. Below it, write them as arbitrary properties, as in [margin-block-start:theme(spacing.4)].
• Write colors in oklch(), with none as the hue of a gray, white or black. Derive a hover, tint or transparent version with color-mix(in oklch, …).
• Put sizes that grow with the screen in one clamp() token.
• Put every :hover rule inside @media (hover: hover) and (pointer: fine).
• Style focus with :focus-visible and outline. Never write outline: none.
• Give everything pressable an :active state.
• Put a transition that moves or scales something inside @media (prefers-reduced-motion: no-preference). Name its properties, never all, and never use ease-in.
• Cut off overflow with overflow: clip. Keep hidden for an element a script scrolls.

Read the entry before you write

Each file holds entries with the CSS and its rules. The rules are the conditions the CSS needs to work, so keep all of them. Read only the files whose row matches what you are about to write. One component matches two or three, and a whole page matches most of them.

Left out on purpose

Never add text-box trim on *, text-rendering: optimizeLegibility, or a reset that puts display: contents or one shared grid cell on every element. references/foundations.md has the reasons.

Browser support

Most entries end with a Support: line. This skill sets no browser floor. Weigh the line against the browsers the project targets, and tell the user when something you used is missing from one of them.

Motion

Whether something should animate, the design or review of motion, springs, gestures and drag, and checks on a real phone belong to Emil Kowalski's skills animate, review-animations, improve-animations, find-animation-opportunities and mobile-native. When they are installed, use them for those jobs, and where one disagrees with a value here, use its value. When they are not, use the entries as written and add no motion beyond what an entry or the task calls for.