TsukiNi22/ai-utils / skills/docs/html-style
html-style
VerifiedThe user's visual style for any HTML page (taken from html-doc - R-Type doc colors + context-forge layout) - color tokens for the light and dark themes, system font stacks and type scale, spacing / radius / layout / breakpoints, components (top bar, cards, callouts, tables, code blocks with copy, content tabs, sidebar, pager, SVG diagram classes, sun/moon theme switch, EN/FR switch), rules (responsive on phone, tablet, TV and touch screens, self-contained, no CDN / web font / gradient / emoji, WCAG contrast in both themes) - with scripts to build a self-contained page (new_page.py) and check a page or a palette (check_style.py). Use whenever creating or restyling an HTML page, a small web tool, a dashboard or a page component for the user, or when defining / changing a palette, color, font or theme, unless the user asks for another style.
HTML style
SKILL_DIR = directory of this file. The source of the style is templates/style.css (CSS) + templates/base.js
(behaviour), extracted from html-doc/templates/technical.html. html-doc (documentation pages) and explain-doc
(explanation pages) are built on it; any other HTML page of the user uses it too.
1. New page
python3 SKILL_DIR/scripts/new_page.py <body.html> -o <out.html> [--css extra.css] [--js extra.js] \
[--actions actions.html] [--lang-switch] --set PROJECT="Name" TITLE="Page title" FOOTER="..."
<body.html> = what goes inside .layout: an optional <aside class="sidebar" id="sidebar"> (contents list) and
<main> (<header> with .page-eyebrow, h1, p.lead, then one <section id> card per topic). The script
inlines style.css + base.js (+ the extra files, after them) into templates/page.html: the result is one
self-contained file that works offline and from file://. --attr NAME=VALUE adds attributes to <html>
(data-page, data-nav-title, data-default-level). Several pages in one folder: scripts/sync_nav.py <folder>
fills the top tabs / previous-next cards of every page (html-doc and explain-doc pages together) and gives
them the same brand and shared top bar controls (GitHub link, EN / FR switch), reporting a page without French. Without a sidebar, add
.layout { grid-template-columns: minmax(0, 1fr); max-width: 880px; } in the extra CSS.
2. Tokens (never a raw color in a component: always var(--x))
| Token | Light | Dark | Use |
|---|---|---|---|
--bg | #efede8 | #15171b | page background (light: warm grey, never pure white - easier on the eyes) |
--surface | #f7f5f0 | #1d2025 | cards, top bar, buttons |
--text | #1d1f23 | #e6e7ea | text |
--muted | #5d636e | #9aa0ab | secondary text, captions, table heads |
--border | #dad6cd | #30343b | borders, separators |
--accent / --accent-soft | #2f5bd3 / #e6ecfb | #7d9cf0 / #232c45 | links, current tab, highlights / their background |
--warn / --warn-soft | #a8540a / #fbefe3 | #f0a868 / #3a2a1b | limits, risks |
--ok / --ok-soft | #1f7a4a / #e3f4ea | #6fcf97 / #1b3326 | validated, good practice |
--code-bg | #e9e6df | #24272d | inline code, code blocks, hover |
--node / --node-alt / --line | #f7f5f0 / #eef1f8 / #868c97 | #23262c / #283043 / #747a85 | SVG boxes / highlighted box / edges |
Dark theme: the same tokens in @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {...} }
and :root[data-theme="dark"] {...} (the switch forces one or the other). A new token is added in the 3 blocks.
3. Type, space, layout
- Fonts (no web font): text
system-ui, -apple-system, "Segoe UI", Roboto, sans-serif16px / 1.6; codeui-monospace, SFMono-Regular, Menlo, Consolas, monospace(0.9em inline, 13.5px blocks). - Scale:
h134px (27px mobile),h222px,h317px, lead 17px muted, body 16px, tables 14.5px, captions / footer 13px, eyebrow / table heads / sidebar title 12-13px uppercase with letter spacing (.04em-.1em). - Text width
75chmax (70chfor the lead). Radius: cards 10px, code blocks 8px, tabs / buttons 6px, inline code 4px, pills 999px. Card padding 28px 32px (20px 16px mobile), 24px between cards. - Layout
.layout: sidebar 250px + content, max 1180px; from 1340px the content column (880px) is centered and the sidebar sits on its left. Breakpoints 480 / 600 / 860px (sidebar off-canvas, menu button, tabs hidden) / 1100 / 1340 / 1900px, see the Responsive rule. - Logo of the brand (one for the whole site, never one per page): always ask (AskUserQuestion, French) when
the site has none chosen yet or the user wants to change it - "Quel logo pour la documentation ?":
Logo du dépôt(one option per logo found:scripts/set_logo.py <docs dir> --list, preview its path), only when the repository has one;Logo personnalisé- a logo made for the project as a whole (what it is / does, not the topic of one page): inline SVGviewBox="0 0 32 32", 2-3 simple shapes readable at 26px,currentColor(= accent) + at most one token color, no text longer than 2 letters; describe it in the option (and draw it in thepreview);Logo de documentation(the default one oftemplates/page.html). A site that already has its logo keeps it without asking (sync_nav.pycopies the brand of the html-doc pages). Apply the answer on every page:scripts/set_logo.py <docs dir> --file <logo>(repository or custom SVG saved as<docs dir>/logo.svg) or--default. An SVG is inlined and cleaned (scripts, events, metadata removed, ids prefixed), a raster image becomes a data URI.
- Top bar 56px sticky:
.brand(inline SVG logo incurrentColor= accent, name,.verbadge hidden when empty; the same on every page of a site, copied bysync_nav.py),nav.tabs,.spacer,.top-actions(icon buttons | divider | EN/FR pill, theme switch).
4. Components (classes of style.css)
| Need | Markup |
|---|---|
| card per topic | <section id="x"><h2>N. Title</h2>...</section> (anchor # added on hover) |
| page header | <header><div class="page-eyebrow">Kind</div><h1>...</h1><p class="lead">...</p></header> |
| remark / limit / validated | <div class="callout">, .callout.warn, .callout.ok |
| table | <div class="table-wrap"><table><thead>... (muted uppercase heads, row lines); base.js adds the box when it is missing, keeps the short cells on one line (never three words on three lines) as long as the table fits, lets a word over 32 characters break, and the table scrolls in its box when nothing else fits (.no-fit on a table to leave it alone; a table added later: docTables.watch(table)) |
| anything else | h4-h6, hr, blockquote, kbd, mark, samp, abbr, small, details / summary, dl, caption, fieldset / legend, fields and plain buttons are styled by the template (:where() rules: any rule of a component wins); fields and scrollbars follow the theme by color-scheme |
| code | <code> inline; <pre data-title="File"><code> block (1px --border outline so it shows on the page, title bar, Copy button; data-nocopy to remove) |
| alternatives | <div class="ctabs" data-tabs="g"><button data-tab="a"> + <div class="ctab-panel" data-tabs="g" data-tab="a"> |
| contents list | <aside class="sidebar" id="sidebar"><p>Contents</p><a href="#x">1. ...</a> (visible section highlighted) |
| previous / next | <nav class="pager"><a href="..."><span>Previous</span>Title</a><a class="next"> |
| diagram | <figure><svg viewBox="0 0 760 H" role="img" aria-label="..."> + <figcaption>Figure N: ... |
| icon button | <a class="icon-btn" aria-label="..."> + 16-18px inline SVG in currentColor |
- A figure is never drawn above its
viewBoxwidth (base.jscaps it: on a wide screen the labels would grow); draw it at the size it is read (viewBox="0 0 760 H", labels 11.5-13px). - Arrows are computed, not typed:
<path class="edge" data-from="a" data-to="b" marker-end="url(#arr)"/>(a/b= id of arect/circle/ellipse, or of a<g>holding one);data-from="a:right"picks a side (top,bottom,left,right),data-bend="-0.2"curves it (negative = above a left-to-right arrow),data-gapleaves space; a label<text data-label-for="<path id>" data-offset="-8">is put on its middle.base.jswrites thedfrom the shapes, so an arrow always starts and ends on them; several arrows reaching the same side of a box (without:side) are spread along it (never one point, never superposed). A hand-written arrow must start and end on a shape border (check_style.pyreports the others;data-freefor an arrow pointing to nothing on purpose). - Text: inside the drawing (
viewBox), either fully inside a box or fully outside (never across its border),text-anchor="middle"for centered labels. - SVG classes:
box,box-alt(accent border),group(dashed frame),lbl,small,title,mono/mono-s(values, code, file content in monospace),edge,edge-accent,dash,arrow,arrow-accent(markers once in<defs>, theirfillbyarrow/arrow-accent, never left black). They follow the theme by themselves; only these classes on texts and shapes (an invented one has no colour of its own), never a hard-codedfill/strokecolour - check the drawing in both themes. - Choices shared by the site: the theme, language and level are saved under
<data-storage-key>-theme|lang|level(one key for the site, set bysync_nav.py) and carried by the links between the pages (?lang=fr&theme=dark &level=technical, read on arrival): a choice made on one page applies to all of them, also fromfile://where each page has its own storage. - Bilingual page:
--lang-switch, content as<span data-lang="en">..</span><span data-lang="fr">..</span>, UI strings withdata-i18ntranslated bywindow.DOC_FR(html-docexplains it in full). English only by default. - A new component: built from the tokens, the same radius / spacing, a hover with
--accentborder or--code-bgbackground, a visible:focus-visible(2px accent outline), works at 860px / 480px and in both themes.
5. Rules
- Self-contained: inline CSS / JS / SVG, no CDN, no framework, no web font, no external image (inline SVG or
data:URI); no gradient, no emoji, no shadow except the floating ones (open menu, popovers). - Accessible by the template (RGAA 4.1):
page.htmlstarts with a skip link to<main id="main">(new_page.pywrites the id),langon<html>, a visible:focus-visible; your body markup gives everythascope, every scrolling block (pre, a wide table)tabindex="0"+role="region"+ a name, and never skips a heading level. - Contrast WCAG AA in both themes: text >= 4.5:1, lines / meaningful graphics >= 3:1.
- Scrollbars: thin, a transparent track and a rounded thumb from
--line(stronger on hover), never the browser's default bar (on Linux a wide grey track appears on hover): the "scrollbars" block oftemplates/style.css, keep it. - An element with its own background (
code,kbd,mark, badge) inside an element that sets a light text color (accent button, dark table head, colored banner) gets an explicit override (th code { background: rgba(255,255,255,.18); color: #fff; }): it never inherits a color unreadable on its own background (check_style.pyfinds them). - Responsive (every page, every platform): the pages must work as well on a phone, a tablet, a TV, a foldable
or a touch laptop as on a desktop (
templates/style.css, "Responsive" block, already in the templates - keep it):<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">, neveruser-scalable=no/maximum-scale=1;text-size-adjust: 100%; safe-area insets (env(safe-area-inset-*)) on the bar, the layout and the footer (notches, rounded corners, landscape);- mobile first thinking, breakpoints 480 / 600 / 860 / 1100 / 1340 / 1900px (phone, large phone, tablet and
off-canvas menu, small laptop, centered column, TV / 4K bigger base font) + short landscape screens
(
max-height: 480px); no fixed width beyondmin(..., 100%), tables / code / formulas / wide drawings scroll inside their own box (.table-wrap,pre,.formula), long words / paths wrap (overflow-wrap); - touch: nothing that needs hover -
@media (hover: none)shows the copy buttons / anchors, no tooltip that needs a hover (dfnopens on tap / focus),@media (pointer: coarse)gives targets of 44px minimum; form fields 16px on small screens (iOS zooms under that); the sidebar menu closes on a tapped entry, on an outside tap and on Escape; 100dvh (not only 100vh) for full-height panels; - interactions have a touch equivalent (drag = one finger, zoom = pinch, pan = two fingers, tap = click; right
click / Shift / keyboard are shortcuts only),
touch-actionset on canvases; prefers-reduced-motion,forced-colors, and a print style (no bar / sidebar / buttons, cards without border).
- Motion: transitions 0.15-0.3s; animations stop under
@media (prefers-reduced-motion: reduce). localStorage(theme, language, view state) always intry / catchunder<storage-key>-<name>.
6. Define or change a style (palette, color, font)
- Ask (AskUserQuestion, French) when not given: "Quelle palette ?" -
Style par défaut (Recommandé)·Couleur du projet / de la marque(hex or logo given) ·Palette personnalisée. Font: system stacks unless the user asks (then a local / system font, never a downloaded one). - Change only the tokens, never the components: for a project color, set
--accent(light: dark enough for 4.5:1 on--surface; dark: a lighter tint of the same hue),--accent-soft(accent at ~10% on--surface, light; ~20% on--bg, dark), keep the neutrals. A full palette defines every token of section 2 in both themes. - Write it as a
:rootoverride in the page extra CSS (or intemplates/style.csswhen the default itself changes, then the same values in the<style>of thehtml-doctemplates). python3 SKILL_DIR/scripts/check_style.py <page.html|css> [--compare SKILL_DIR/templates/style.css]: 0 error (tokens of both themes, contrast, inherited colors, self-contained, diagrams: arrows touching their shapes, text inside the drawing and not across a box border);--comparelists what differs from the default.
7. Check before delivering
check_style.pyon the page: 0 error (the sources: tokens, contrast of the tokens, avar()defined nowhere, an invalid colour, a tag or a class nothing styles, the viewport, fixed widths).check_render.py <page.html[?query]> [--widths 1280,768,375] [--themes light,dark] [--click SELECTOR ...] [--shots DIR]: 0 error (--clickmeasures again after a click: a menu, a popover, the next step;?q=wordgives the page its state: a search open, an embed mode). Headless Firefox measures what is really drawn, in both themes, at each width, in each language and level the page offers, tab panels and<details>opened: every text against what is really behind it (black on black, a chip in a banner, an SVG text on its box), the page scrolling sideways, what sticks out or starts off the left of the screen, a text past the edge of its card or cell, a word cut by a column too narrow, three words of a cell on three lines in a column under 150 px; as warnings a sentence squeezed in a column, a column twice too wide, an SVG text drawn under 8 px.- Look at it:
--shots DIRwrites a screenshot per theme and width: every text readable, tap targets usable, switches and the menu working. A long or crowded content is worth a try: a table of 20 columns, a word of 100 characters, a very long title, a long project name. - No
{{...}}left (new_page.pyreports them).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |