@greenharness/greenrack-cli 0.0.0-stage → 7.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +335 -2
- package/agents/design-system-lookup.md +59 -0
- package/dist/bin.d.ts +3 -0
- package/dist/bin.d.ts.map +1 -0
- package/dist/bin.js +145 -0
- package/dist/bin.js.map +1 -0
- package/dist/catalog.d.ts +13 -0
- package/dist/catalog.d.ts.map +1 -0
- package/dist/catalog.js +67 -0
- package/dist/catalog.js.map +1 -0
- package/dist/commands/context.d.ts +17 -0
- package/dist/commands/context.d.ts.map +1 -0
- package/dist/commands/context.js +110 -0
- package/dist/commands/context.js.map +1 -0
- package/dist/commands/doctor.d.ts +75 -0
- package/dist/commands/doctor.d.ts.map +1 -0
- package/dist/commands/doctor.js +1008 -0
- package/dist/commands/doctor.js.map +1 -0
- package/dist/commands/hook.d.ts +10 -0
- package/dist/commands/hook.d.ts.map +1 -0
- package/dist/commands/hook.js +323 -0
- package/dist/commands/hook.js.map +1 -0
- package/dist/commands/list.d.ts +4 -0
- package/dist/commands/list.d.ts.map +1 -0
- package/dist/commands/list.js +59 -0
- package/dist/commands/list.js.map +1 -0
- package/dist/commands/lookup.d.ts +13 -0
- package/dist/commands/lookup.d.ts.map +1 -0
- package/dist/commands/lookup.js +66 -0
- package/dist/commands/lookup.js.map +1 -0
- package/dist/commands/manifest.d.ts +5 -0
- package/dist/commands/manifest.d.ts.map +1 -0
- package/dist/commands/manifest.js +33 -0
- package/dist/commands/manifest.js.map +1 -0
- package/dist/commands/mcp.d.ts +159 -0
- package/dist/commands/mcp.d.ts.map +1 -0
- package/dist/commands/mcp.js +235 -0
- package/dist/commands/mcp.js.map +1 -0
- package/dist/commands/mockup.d.ts +80 -0
- package/dist/commands/mockup.d.ts.map +1 -0
- package/dist/commands/mockup.js +714 -0
- package/dist/commands/mockup.js.map +1 -0
- package/dist/commands/skill.d.ts +15 -0
- package/dist/commands/skill.d.ts.map +1 -0
- package/dist/commands/skill.js +398 -0
- package/dist/commands/skill.js.map +1 -0
- package/dist/disambiguation.d.ts +24 -0
- package/dist/disambiguation.d.ts.map +1 -0
- package/dist/disambiguation.js +56 -0
- package/dist/disambiguation.js.map +1 -0
- package/dist/extension-pointer.d.ts +7 -0
- package/dist/extension-pointer.d.ts.map +1 -0
- package/dist/extension-pointer.js +30 -0
- package/dist/extension-pointer.js.map +1 -0
- package/dist/format.d.ts +19 -0
- package/dist/format.d.ts.map +1 -0
- package/dist/format.js +213 -0
- package/dist/format.js.map +1 -0
- package/dist/hook-script.d.ts +73 -0
- package/dist/hook-script.d.ts.map +1 -0
- package/dist/hook-script.js +165 -0
- package/dist/hook-script.js.map +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6 -0
- package/dist/index.js.map +1 -0
- package/dist/legacy-names.d.ts +26 -0
- package/dist/legacy-names.d.ts.map +1 -0
- package/dist/legacy-names.js +26 -0
- package/dist/legacy-names.js.map +1 -0
- package/dist/manifest.d.ts +51 -0
- package/dist/manifest.d.ts.map +1 -0
- package/dist/manifest.js +229 -0
- package/dist/manifest.js.map +1 -0
- package/dist/registry-types.d.ts +106 -0
- package/dist/registry-types.d.ts.map +1 -0
- package/dist/registry-types.js +2 -0
- package/dist/registry-types.js.map +1 -0
- package/dist/registry.d.ts +52 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +95 -0
- package/dist/registry.js.map +1 -0
- package/dist/scan.d.ts +19 -0
- package/dist/scan.d.ts.map +1 -0
- package/dist/scan.js +29 -0
- package/dist/scan.js.map +1 -0
- package/dist/search.d.ts +16 -0
- package/dist/search.d.ts.map +1 -0
- package/dist/search.js +75 -0
- package/dist/search.js.map +1 -0
- package/dist/skill-template.d.ts +24 -0
- package/dist/skill-template.d.ts.map +1 -0
- package/dist/skill-template.js +140 -0
- package/dist/skill-template.js.map +1 -0
- package/greenharness.toml +38 -0
- package/package.json +76 -3
- package/registry.json +12893 -0
- package/skills/colors/LICENSE +21 -0
- package/skills/colors/NOTICE.md +36 -0
- package/skills/colors/SKILL.md +101 -0
- package/skills/colors/color-formats.md +90 -0
- package/skills/colors/color-usage.md +109 -0
- package/skills/colors/contrast.md +70 -0
- package/skills/colors/palette-generation.md +108 -0
- package/skills/colors/palette-structure.md +72 -0
- package/skills/colors/token-naming.md +99 -0
- package/skills/greenrack-mockup/SKILL.md +115 -0
- package/skills/typography/LICENSE +21 -0
- package/skills/typography/NOTICE.md +36 -0
- package/skills/typography/SKILL.md +171 -0
- package/skills/typography/choosing-fonts.md +53 -0
- package/skills/typography/css-cheat-sheet.md +67 -0
- package/skills/typography/details-and-accessibility.md +84 -0
- package/skills/typography/spacing-and-sizing.md +87 -0
- package/skills/typography/variable-fonts-and-opentype.md +100 -0
- package/skills/typography/wrapping-and-punctuation.md +23 -0
- package/skills/ui/LICENSE +21 -0
- package/skills/ui/NOTICE.md +38 -0
- package/skills/ui/SKILL.md +141 -0
- package/skills/ui/animations.md +170 -0
- package/skills/ui/enter-exit.md +157 -0
- package/skills/ui/icon-transitions.md +72 -0
- package/skills/ui/icons.md +105 -0
- package/skills/ui/performance.md +63 -0
- package/skills/ui/surfaces.md +166 -0
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Token naming
|
|
2
|
+
|
|
3
|
+
Naming is what makes a palette usable by anyone who did not build it. For which ramps exist and what each step does, see [palette-structure.md](palette-structure.md).
|
|
4
|
+
|
|
5
|
+
## Two tiers
|
|
6
|
+
|
|
7
|
+
**Primitives** name a value. They are the ramp, named by hue and step, as in `--blue-600` or `--neutral-200`. A primitive describes what the color *is*, so it never changes meaning between themes and is never applied directly in a component.
|
|
8
|
+
|
|
9
|
+
**Semantics** name a job. They point at a primitive and take the name of the role they fill, as in `--color-text-secondary` or `--color-border-subtle`. Components only ever reference this tier.
|
|
10
|
+
|
|
11
|
+
```css
|
|
12
|
+
:root {
|
|
13
|
+
/* Tier 1: primitives, named by hue and step. Never used directly. */
|
|
14
|
+
--blue-600: #2563eb;
|
|
15
|
+
--neutral-200: #e5e7eb;
|
|
16
|
+
--neutral-700: #374151;
|
|
17
|
+
|
|
18
|
+
/* Tier 2: semantics, named by role. This is what components use. */
|
|
19
|
+
--color-accent-solid: var(--blue-600);
|
|
20
|
+
--color-border: var(--neutral-200);
|
|
21
|
+
--color-text-secondary: var(--neutral-700);
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The tiering is what makes theming possible. Dark mode, a white-label theme and an increased-contrast variant all repoint the semantic tier, leaving the primitives and every component untouched. A codebase applying `--blue-600` directly in components has no theming seam. Adding one later means auditing every usage to work out which meant "the accent" and which just wanted blue.
|
|
26
|
+
|
|
27
|
+
Add a third, component-level tier (`--color-button-danger-bg`) only where a component genuinely and intentionally diverges from the system. One component token is a documented exception; twenty mean the semantic tier is missing roles.
|
|
28
|
+
|
|
29
|
+
## The role inventory
|
|
30
|
+
|
|
31
|
+
A system is complete when every role below has a token. Build against this list rather than adding tokens as components demand them, or the palette ends up shaped like whichever screen came first.
|
|
32
|
+
|
|
33
|
+
| Group | Roles |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| Surfaces | page background, surface, raised (menus, popovers), sunken (inputs, wells), overlay scrim |
|
|
36
|
+
| Text | primary, secondary, disabled, inverse, on-accent |
|
|
37
|
+
| Borders | subtle, default, strong, focus ring, separator |
|
|
38
|
+
| Accent | subtle background, border, solid, solid hover, text |
|
|
39
|
+
| Status | per status shipped: subtle background, border, solid, text |
|
|
40
|
+
|
|
41
|
+
Separator and border are separate roles even when they share a value today. A separator divides content; a border encloses a control. They diverge the first time someone restyles inputs, and a system that conflated them gets untangled at that moment.
|
|
42
|
+
|
|
43
|
+
## Naming grammar
|
|
44
|
+
|
|
45
|
+
Use one shape and never deviate. Neutral roles lead with the property, as `--color-{bg|text|border}-{variant}-{state}`. Accent and status roles lead with the role, as `--color-{accent|danger|…}-{subtle|border|solid|text}-{state}`.
|
|
46
|
+
|
|
47
|
+
```css
|
|
48
|
+
--color-bg-surface
|
|
49
|
+
--color-text-secondary
|
|
50
|
+
--color-border-strong
|
|
51
|
+
--color-accent-solid-hover
|
|
52
|
+
--color-danger-subtle
|
|
53
|
+
--color-accent-text
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Pick one word per concept and use only that word. Consistency matters more than the vocabulary. A reader who has seen `--color-text-primary` must be able to guess `--color-text-disabled` without looking:
|
|
57
|
+
|
|
58
|
+
| Concept | Pick one | Never mix in |
|
|
59
|
+
| --- | --- | --- |
|
|
60
|
+
| Foreground | `text` | `fg`, `foreground`, `content`, `ink` |
|
|
61
|
+
| Background | `bg` | `background`, `surface` as a synonym, `fill` |
|
|
62
|
+
| Edge | `border` | `stroke`, `outline`, `line` |
|
|
63
|
+
| Brand color | `accent` | `primary`, `brand`, `theme` used interchangeably |
|
|
64
|
+
|
|
65
|
+
Reserve `primary` for exactly one meaning. `--color-text-primary` for body text beside `--color-primary` for the brand is the most common naming collision there is, and it makes every `primary` token ambiguous until you open its definition. Use `accent` for the brand and let `primary` mean "the most prominent of its group".
|
|
66
|
+
|
|
67
|
+
## Anti-patterns
|
|
68
|
+
|
|
69
|
+
| Name | Problem | Instead |
|
|
70
|
+
| --- | --- | --- |
|
|
71
|
+
| `--color-blue-button` | Appearance at the semantic tier; lies the moment the brand changes | `--color-accent-solid` |
|
|
72
|
+
| `--color-sidebar-gray` | Named for where it was used first; the second usage makes it nonsense | `--color-bg-surface` |
|
|
73
|
+
| `--color-light-gray` | Lies in dark mode, where it is the dark one | `--neutral-200` as a primitive |
|
|
74
|
+
| `--color-text-2` | Numbered semantics carry no meaning; nobody can guess what `3` would be | `--color-text-secondary` |
|
|
75
|
+
| `--color-gray-hover` | Mixes a hue with a state and belongs to no tier | `--color-bg-surface-hover` |
|
|
76
|
+
| `--blue-600` used in a component | Skips the semantic tier and removes the theming seam | Point a semantic token at it |
|
|
77
|
+
|
|
78
|
+
## In Tailwind projects
|
|
79
|
+
|
|
80
|
+
Tailwind v4 generates utilities from `@theme`, so names declared there become the API. Declare primitives and semantics in the same block; the `--color-*` namespace is what produces `bg-*`, `text-*` and `border-*`:
|
|
81
|
+
|
|
82
|
+
```css
|
|
83
|
+
@theme {
|
|
84
|
+
/* Primitives */
|
|
85
|
+
--color-blue-50: #eff6ff;
|
|
86
|
+
--color-blue-600: #2563eb;
|
|
87
|
+
--color-blue-900: #1e3a8a;
|
|
88
|
+
|
|
89
|
+
/* Semantics: what templates should use */
|
|
90
|
+
--color-accent-solid: var(--color-blue-600);
|
|
91
|
+
--color-text-secondary: var(--color-neutral-700);
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
That yields `bg-accent-solid` and `text-text-secondary` alongside `bg-blue-600`. Tailwind prefixes every `--color-*` name with the utility, so a `text-` token doubles. Accept the doubling, or follow the convention the project already uses. Both tiers are reachable, so the discipline is a convention rather than a constraint. Templates use the semantic utilities, and a raw `bg-blue-600` in a component is the thing to flag.
|
|
96
|
+
|
|
97
|
+
Repoint semantics for dark mode in a `.dark` block outside `@theme`. Leave the block without `inline`, so utilities read the semantic variable at render time.
|
|
98
|
+
|
|
99
|
+
Opacity modifiers work on either tier, as in `bg-accent-solid/50`. But a color carrying alpha cannot be contrast-checked against a static background, because what it renders depends on what sits behind it. Use solid tokens for anything with text on it.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: greenrack-mockup
|
|
3
|
+
description: Take a new screen from mockup directions to an implemented, verified PR without leaving the greenrack design system. Use whenever the user asks for a screen, a page, a UI proposal, mockups, or "show me options" in a repo that consumes @greenharness/greenrack-ui — and when planning (plan mode) a new screen or a material layout, hierarchy or interaction change there.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Gate.** This skill applies only in a repository whose `package.json` depends on `@greenharness/greenrack-ui`, or on the old `@duro-app/ui` it replaces (a `workspace:` dependency counts). Anywhere else, stop: do not apply it.
|
|
7
|
+
|
|
8
|
+
# greenrack-mockup
|
|
9
|
+
|
|
10
|
+
GENERATED by `greenrack skill install` — do not hand-edit. Regenerate:
|
|
11
|
+
`npx -y @greenharness/greenrack-cli@^7.0.0 skill install` (`--check` verifies it in CI). Repo-specific notes
|
|
12
|
+
live in `.claude/greenrack-mockup.local.md`; read it if it exists.
|
|
13
|
+
|
|
14
|
+
Standing rule (fleet decision `ui.mockup-handoff`): a mockup is written in
|
|
15
|
+
the design system's own vocabulary, and the direction the user picks is a
|
|
16
|
+
contract. What binds: layout, hierarchy, states, the `data-gr` component
|
|
17
|
+
map and the token names, sizes and border widths included (ADR-0027). What
|
|
18
|
+
does not bind: positions (top, left, inset, transform).
|
|
19
|
+
|
|
20
|
+
**This overrides the `design` skill's step 0.** That skill says to lift
|
|
21
|
+
resolved values from the real stylesheets. Here you never write a resolved
|
|
22
|
+
value: every colour, spacing, radius, font, shadow and duration is a
|
|
23
|
+
`var(--gr-*)` from the seeded token block, and every element a person can
|
|
24
|
+
act on carries `data-gr="<Component>"`. Everything this workflow needs ships
|
|
25
|
+
with the CLI: `mockup seed` writes the artboard, `mockup check` gates it and
|
|
26
|
+
`mockup canvas` builds the page the person picks from.
|
|
27
|
+
|
|
28
|
+
## Args
|
|
29
|
+
|
|
30
|
+
- `propose <screen>` — seed 2–4 direction artboards, check them, publish the canvas.
|
|
31
|
+
- `implement <screen> <direction>` — build the picked direction from its component map.
|
|
32
|
+
- `prove <route>` — screenshot the built route and assemble the PR section.
|
|
33
|
+
- no args — infer the stage from what exists under `docs/mockups/<screen>/`.
|
|
34
|
+
|
|
35
|
+
## propose
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npx -y @greenharness/greenrack-cli@^7.0.0 mockup seed --out docs/mockups/<screen> --name Main # direction A
|
|
39
|
+
npx -y @greenharness/greenrack-cli@^7.0.0 mockup seed --out docs/mockups/<screen> --name <Direction> # B, C, …
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- `<screen>` is kebab-case (`approval-gates`). Artboards are committed with
|
|
43
|
+
the PR — never leave them in a scratch directory; a session scratchpad is
|
|
44
|
+
garbage-collected and the canvas URL would be the only surviving artefact.
|
|
45
|
+
- Author each artboard inside the seeded `<style>` and root div. Colours,
|
|
46
|
+
spacing, radii, sizes, border widths, type, shadows and motion come only
|
|
47
|
+
from the token block (`var(--gr-size-*)`, `var(--gr-border-*)`);
|
|
48
|
+
positions are yours, and the root keeps the seeded canvas size
|
|
49
|
+
(`var(--gr-mockup-canvas-width)` / `-height`). A custom property you define
|
|
50
|
+
outside the token block holds a token too (`--gap: var(--gr-spacing-md)`);
|
|
51
|
+
`--gap: 12px` is the same raw value one `var()` away. Every button, row, chip, tab,
|
|
52
|
+
input, link, table and dialog — whatever element it is drawn as — carries
|
|
53
|
+
`data-gr="<Component>"` or `data-gr="<Component>.<Part>"`, using names
|
|
54
|
+
from `npx -y @greenharness/greenrack-cli@^7.0.0 list components`. Notes for the implementer go after the
|
|
55
|
+
name: `data-gr="Button variant=primary"`.
|
|
56
|
+
- Start from a recipe when one fits the screen shape (`npx -y @greenharness/greenrack-cli@^7.0.0 list recipes`
|
|
57
|
+
— admin-detail-page, split-pane, page-with-sidenav, settings-page, …) and
|
|
58
|
+
say so in the artboard's header comment; a hand-rolled layout needs a reason.
|
|
59
|
+
- Gate before publishing:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npx -y @greenharness/greenrack-cli@^7.0.0 mockup check docs/mockups/<screen>/*.dc.html
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Exit 1 lists `file:line rule: message`. Fix every finding; do not publish
|
|
66
|
+
an artboard that fails. A note that `@greenharness/greenrack-ui` differs from the
|
|
67
|
+
checker means an `unknown-component` may only be newer than the checker:
|
|
68
|
+
rerun with the version the note names before changing the artboard.
|
|
69
|
+
- Build the review page, one self-contained file with every direction under a
|
|
70
|
+
letter (it refuses while any artboard fails the check):
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npx -y @greenharness/greenrack-cli@^7.0.0 mockup canvas docs/mockups/<screen>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Publish `docs/mockups/<screen>/canvas.html` as the Artifact (the
|
|
77
|
+
`greenrack_mockup_canvas` MCP tool returns the same page from the artboards'
|
|
78
|
+
HTML). Where Artifacts are unavailable, open it locally in the browser and
|
|
79
|
+
say so; the pick does not wait on publishing.
|
|
80
|
+
- Ask the user to pick a direction. Record the answer as
|
|
81
|
+
`<canvas URL> · direction <X>` — it goes in the PR.
|
|
82
|
+
- Delete the directions that were not picked, rebuild the canvas, and commit
|
|
83
|
+
the picked artboards: the files in `docs/mockups/` are the contract, the
|
|
84
|
+
canvas is the review surface.
|
|
85
|
+
|
|
86
|
+
## implement
|
|
87
|
+
|
|
88
|
+
- Read the picked artboard. Its `data-gr` attributes ARE the component
|
|
89
|
+
list: for each one, `npx -y @greenharness/greenrack-cli@^7.0.0 <Component>` (or the `greenrack_lookup` MCP
|
|
90
|
+
tool) gives props and usage. Do not substitute a hand-rolled element for a
|
|
91
|
+
named component; if a named component does not fit, say so and propose the
|
|
92
|
+
design-system change rather than working around it.
|
|
93
|
+
- Tokens map one to one: `var(--gr-spacing-md)` is `spacing.md` from
|
|
94
|
+
`@greenharness/greenrack-tokens/tokens/spacing.css`, `--gr-color-bg-card` is
|
|
95
|
+
`colors.bgCard`, `--gr-radius-sm` is `radii.sm`, `--gr-typography-*`
|
|
96
|
+
and `--gr-type-scale-*` are `typography`/`typeScale`, `--gr-shadow-*`
|
|
97
|
+
is `shadows`, `--gr-duration-*`/`--gr-easing-*` are `duration`/`easing`.
|
|
98
|
+
A media query on `768px` is `breakpoints.md` from
|
|
99
|
+
`@greenharness/greenrack-tokens/tokens/breakpoints.css`. The lint config refuses the raw
|
|
100
|
+
value, so write the token the first time.
|
|
101
|
+
- Layout comes from a recipe before a grid: `npx -y @greenharness/greenrack-cli@^7.0.0 <recipe> --source-only`.
|
|
102
|
+
- Positions in the artboard are a sketch: match its hierarchy and states.
|
|
103
|
+
Its sizes are tokens, so they bind like colours do; a size the artboard
|
|
104
|
+
needs and no token has is added to `@greenharness/greenrack-tokens` first.
|
|
105
|
+
|
|
106
|
+
## prove
|
|
107
|
+
|
|
108
|
+
- Run the app, load the route in a real browser (Chrome MCP), and take a
|
|
109
|
+
screenshot at the artboard's width (1120px) in the artboard's theme.
|
|
110
|
+
- The PR body carries, under `## Mockup`: the canvas URL and direction, the
|
|
111
|
+
path `docs/mockups/<screen>/`, and the artboard next to the live screenshot.
|
|
112
|
+
A PR that touches no screen writes `Mockup: none` instead. CI checks for
|
|
113
|
+
one or the other.
|
|
114
|
+
- If the screenshot and the artboard disagree on hierarchy or states, that is
|
|
115
|
+
a finding to fix, not a caption to write.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jakub Krehel
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Notice
|
|
2
|
+
|
|
3
|
+
This skill is a fork of `better-typography/` from the repository `jakubkrehel/skills`, at commit `4c66b1fa86e9ab70187b43d7da9b6fdb29f2ef63`, fetched 2026-10-16.
|
|
4
|
+
|
|
5
|
+
Local edits:
|
|
6
|
+
|
|
7
|
+
- Renamed by `scripts/fork-interface-skills.sh` at dotfiles commit `5fbdc4b` (`better-typography` to `typography`).
|
|
8
|
+
- Dropped `agents/openai.yaml`.
|
|
9
|
+
- Added the precedence block after the introduction of `SKILL.md`.
|
|
10
|
+
- Reconciled the clause in `ui/SKILL.md` that limited project tokens, so a project token always wins.
|
|
11
|
+
|
|
12
|
+
Updating: diff upstream from the pinned commit, have a frontier model port the changes over the local edits, then bump the pin.
|
|
13
|
+
|
|
14
|
+
The upstream license (MIT) applies; the text is in `LICENSE`:
|
|
15
|
+
|
|
16
|
+
> MIT License
|
|
17
|
+
>
|
|
18
|
+
> Copyright (c) 2026 Jakub Krehel
|
|
19
|
+
>
|
|
20
|
+
> Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
21
|
+
> of this software and associated documentation files (the "Software"), to deal
|
|
22
|
+
> in the Software without restriction, including without limitation the rights
|
|
23
|
+
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
24
|
+
> copies of the Software, and to permit persons to whom the Software is
|
|
25
|
+
> furnished to do so, subject to the following conditions:
|
|
26
|
+
>
|
|
27
|
+
> The above copyright notice and this permission notice shall be included in all
|
|
28
|
+
> copies or substantial portions of the Software.
|
|
29
|
+
>
|
|
30
|
+
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
31
|
+
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
32
|
+
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
33
|
+
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
34
|
+
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
35
|
+
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
36
|
+
> SOFTWARE.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: typography
|
|
3
|
+
description: Sets and reviews how text renders in your product, from the type scale and spacing to font features, wrapping, truncation and punctuation.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
**Gate.** This skill applies only in a repository whose `package.json` depends on `@greenharness/greenrack-ui`, or on the old `@duro-app/ui` it replaces (a `workspace:` dependency counts). Anywhere else, stop: do not apply it.
|
|
7
|
+
|
|
8
|
+
# Typography
|
|
9
|
+
|
|
10
|
+
This skill sets and reviews how text renders, from the type scale and spacing to font loading, wrapping and punctuation. It writes every fix in the project's styling system, and the [cheat sheet](css-cheat-sheet.md) maps each declaration to its Tailwind utility.
|
|
11
|
+
|
|
12
|
+
A decision of this repository (resolved at its applicable scope with `aval resolve`) outranks a value in this skill. Apply token requirements and gap routing only where the repository's decisions require them, keeping their named exemptions. On `duro-stack`, a non-exempt measure without a token is a design-system gap under ADR-0006/0027, never a local literal.
|
|
13
|
+
|
|
14
|
+
Where greenrack defines the value, these win: the CLAUDE.md "Typography Presets" table, `typography.css.ts` and `type-presets.css.ts`.
|
|
15
|
+
|
|
16
|
+
The words belong to `writing`, semantic heading structure to `accessibility` and spatial RTL layout to `layout`. Measure contrast with `colors`; whether it passes is `accessibility`'s.
|
|
17
|
+
|
|
18
|
+
## Measured, not preferred
|
|
19
|
+
|
|
20
|
+
Some values here are exact. Unitless line-height, weight `400` or heavier below `18px`, a 60–75 character measure, `16px` inputs on iOS and `tabular-nums` on changing values are findings when missed.
|
|
21
|
+
|
|
22
|
+
Letter-spacing, pairing and scale ratios are heuristics. Report them only where they break the project's own scale. Never propose a new typeface, paid or free, unless the task asks for a type change.
|
|
23
|
+
|
|
24
|
+
## Fewer fonts, sizes and weights
|
|
25
|
+
|
|
26
|
+
Rarely use more than three fonts; marketing pages can carry more than apps. Weight and size carry hierarchy, so each extra one dilutes it. Pair for contrast. A serif headline over a sans body reads as deliberate, two near-identical sans-serifs read as a mistake.
|
|
27
|
+
|
|
28
|
+
Below `18px`, use weight `400` or heavier. Weights `100`–`300` belong at `28px` and up, checked against the background even there. Categories, `Display` and `Text` cuts, formats and fallback stacks are in [choosing-fonts.md](choosing-fonts.md).
|
|
29
|
+
|
|
30
|
+
## Load the faces the design uses
|
|
31
|
+
|
|
32
|
+
Browsers synthesize a weight or style the family doesn't ship, distorting the face. Load every face the design uses. Disable synthesis only after verifying the fallback stack, and only the unwanted mode. The [synthesis longhands](variable-fonts-and-opentype.md#disable-synthesis-narrowly) show how.
|
|
33
|
+
|
|
34
|
+
## Properties over raw tags
|
|
35
|
+
|
|
36
|
+
When a CSS property exists, use it. `font-weight: 650`, not `font-variation-settings: "wght" 650`. `font-variant-numeric: tabular-nums`, not `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders.
|
|
37
|
+
|
|
38
|
+
Leave `font-optical-sizing` at its default `auto`. Hard-code `"opsz"` only when the design deliberately decouples optical size from font size. Reserve raw tags for custom axes like `"GRAD" 80` and features with no property, like `"ss01" 1`. Axes, features and variable versus static files are in [variable-fonts-and-opentype.md](variable-fonts-and-opentype.md).
|
|
39
|
+
|
|
40
|
+
## Use a type scale with semantic names
|
|
41
|
+
|
|
42
|
+
Define a small set of sizes and deviate from it as little as possible. Pair each size with its line-height and weight, so a role is one decision instead of three.
|
|
43
|
+
|
|
44
|
+
Solo, default names like `text-sm` are fine when the usage rules are clear. On a team, name sizes by use (`text-body-sm`) so the rules survive other people. A [role-based starting scale](spacing-and-sizing.md#type-scale) is in the reference.
|
|
45
|
+
|
|
46
|
+
## Heading sizes descend with level
|
|
47
|
+
|
|
48
|
+
Map heading levels to descending steps of the scale, so a subordinate heading never overpowers its parent. Deep levels may share a size where the scale runs out of steps, as long as weight or letter-spacing keeps them distinct. A heading is never smaller than body text unless it is a deliberate overline. See the [level mapping](spacing-and-sizing.md#heading-hierarchy).
|
|
49
|
+
|
|
50
|
+
## Line-height by role
|
|
51
|
+
|
|
52
|
+
Display text `1.1`, headings `1.2`–`1.3`, body copy `1.5`–`1.6`. Use unitless values so line-height scales with the font size; a fixed `24px` does not.
|
|
53
|
+
|
|
54
|
+
Tight line-height is for short text. Anything that wraps to three or more lines needs at least `1.4`, even in a height-constrained row. See the [card description example](spacing-and-sizing.md#line-height-for-wrapping-text).
|
|
55
|
+
|
|
56
|
+
## Letter-spacing by size
|
|
57
|
+
|
|
58
|
+
Headings at `24px` and up take `-0.01em` to `-0.02em`. Uppercase labels at `14px` or smaller take `0.05em`. Body copy stays at `0`. Use `em` so tracking scales with the size.
|
|
59
|
+
|
|
60
|
+
Kerning is built into the font and on by default. `font-kerning: none` is never a fix.
|
|
61
|
+
|
|
62
|
+
## Cap the measure
|
|
63
|
+
|
|
64
|
+
Cap long-form text at 60–75 characters per line. Any unit works, as long as a cap exists and the line length lands in range. See [unit choices and the pixel equivalents](wrapping-and-punctuation.md#measure-line-length).
|
|
65
|
+
|
|
66
|
+
## Wrap deliberately
|
|
67
|
+
|
|
68
|
+
- `text-wrap: balance` evens out headings and short descriptions. Never on paragraphs, and Chromium ignores it past six lines.
|
|
69
|
+
- `text-wrap: pretty` keeps a lone word off the last line. Safe on any paragraph, long-form included.
|
|
70
|
+
- `overflow-wrap: break-word` where a long word, link or ID could escape the container.
|
|
71
|
+
- `white-space: nowrap` on labels and badges where a line break looks broken.
|
|
72
|
+
|
|
73
|
+
Keep interface text at `text-align: start`. `justify` belongs only in specific editorial layouts.
|
|
74
|
+
|
|
75
|
+
## Tabular numbers on changing values
|
|
76
|
+
|
|
77
|
+
Apply `font-variant-numeric: tabular-nums` to timers, counters, prices and numeric table columns, so every digit keeps one width and nothing shifts. Leave figures in prose proportional.
|
|
78
|
+
|
|
79
|
+
## Truncate with a way back
|
|
80
|
+
|
|
81
|
+
For one line, `overflow: hidden`, `text-overflow: ellipsis` and `white-space: nowrap`, which Tailwind's `truncate` sets together. For several, `display: -webkit-box`, `-webkit-box-orient: vertical`, `-webkit-line-clamp: 3` and `overflow: hidden`, which Tailwind's `line-clamp-3` emits.
|
|
82
|
+
|
|
83
|
+
A truncated value needs a way back to the full text, which `layout` owns.
|
|
84
|
+
|
|
85
|
+
## Natural case, typographic punctuation
|
|
86
|
+
|
|
87
|
+
Store text in natural case and set case with `text-transform`, so a redesign never means rewriting copy.
|
|
88
|
+
|
|
89
|
+
Rendered text uses typographic characters, never their keyboard stand-ins. Curly quotes, en dashes, the ellipsis character and non-breaking spaces are in the [substitution table](wrapping-and-punctuation.md#smart-punctuation). Code keeps straight quotes.
|
|
90
|
+
|
|
91
|
+
## Underlines from the font
|
|
92
|
+
|
|
93
|
+
Set `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune `text-underline-offset` and thickness by hand. A dotted `text-decoration-style` hints that a word carries extra information, such as an abbreviation or a defined term. See the [underline recipes](details-and-accessibility.md#underlines).
|
|
94
|
+
|
|
95
|
+
Color is the only part of a real underline that animates reliably. Any other underline animation needs a separate element, and its motion is `ui`'s.
|
|
96
|
+
|
|
97
|
+
## Inputs at 16px on mobile
|
|
98
|
+
|
|
99
|
+
iOS Safari zooms the whole page when an input's text is smaller than `16px`. Two fixes hold `16px` and look different, so ask which one the design wants:
|
|
100
|
+
|
|
101
|
+
- Size the input up on mobile (`text-base sm:text-sm`). Changes how it looks on small screens.
|
|
102
|
+
- Keep `font-size: 16px` and render the intended size with `transform: scale()`. Identical at every viewport, more code to maintain.
|
|
103
|
+
|
|
104
|
+
Both recipes, plus placeholder and caret styling, are in [details-and-accessibility.md](details-and-accessibility.md#forms-and-editable-text).
|
|
105
|
+
|
|
106
|
+
## Size floors
|
|
107
|
+
|
|
108
|
+
Start long-form body text at `16px`, the browser default. Move off it only for a reason you can name, such as a typeface that runs small, a narrow measure or a dense professional tool.
|
|
109
|
+
|
|
110
|
+
UI text can go smaller. Start inputs and menus at `14px` and captions at `13px`, and rarely go below `12px`. Set `font-size` in [`rem`](spacing-and-sizing.md#units) so the reader's browser font size still applies.
|
|
111
|
+
|
|
112
|
+
## Font smoothing on the root
|
|
113
|
+
|
|
114
|
+
Apply `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` once on the root, never per component. Tailwind's `antialiased` sets both.
|
|
115
|
+
|
|
116
|
+
## Language and bidi behavior
|
|
117
|
+
|
|
118
|
+
Set `lang` so browsers and assistive technology pick the right quotes, hyphenation and pronunciation. Set `dir` on the document and wherever direction changes. Wrap a mixed-direction value in `<bdi>` and never reorder digits by hand. How long paragraphs and numbers behave is in [wrapping-and-punctuation.md](wrapping-and-punctuation.md#internationalization).
|
|
119
|
+
|
|
120
|
+
## Trim text boxes in tight containers
|
|
121
|
+
|
|
122
|
+
In buttons and badges, the space a font reserves above and below its letters makes text sit low. `text-box: trim-both cap alphabetic` trims it as a progressive enhancement. See the [edges, keywords and support](spacing-and-sizing.md#text-trimming-with-text-box).
|
|
123
|
+
|
|
124
|
+
## Decorative text in CSS, not images
|
|
125
|
+
|
|
126
|
+
Build drop caps, gradient text, outlines and text shadows in CSS so the text stays selectable and searchable. The [properties and their support](details-and-accessibility.md#decorative-text) are in the reference.
|
|
127
|
+
|
|
128
|
+
## Keep useful text selectable
|
|
129
|
+
|
|
130
|
+
Keep text selectable by default. `::selection` can carry brand into the reading experience, as long as the selected combination stays legible. [Styling other ranges](details-and-accessibility.md#selection) such as search matches is in the reference.
|
|
131
|
+
|
|
132
|
+
`user-select: none` belongs on a draggable or gesture-driven surface where accidental selection interferes. Never across the interface and never because a button label can be highlighted.
|
|
133
|
+
|
|
134
|
+
## Before you finish
|
|
135
|
+
|
|
136
|
+
| Pattern | Fix |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `font-weight` value with no matching weight in the loaded `@font-face` files | Load that face or use a weight the family ships |
|
|
139
|
+
| `font-synthesis: none` on body or interface text | Remove it; set only the unwanted longhand after checking the fallback stack |
|
|
140
|
+
| `font-variation-settings: "wght"` or `"opsz"` | `font-weight`; drop `"opsz"` so `font-optical-sizing: auto` applies |
|
|
141
|
+
| `font-feature-settings: "tnum"` or `"zero"` | `font-variant-numeric: tabular-nums` or `slashed-zero` |
|
|
142
|
+
| `line-height` in `px` or `rem` | A unitless value |
|
|
143
|
+
| `leading-none` or `leading-tight` on a description, card body or anything that can wrap | `1.4` or more |
|
|
144
|
+
| `letter-spacing` in `px` | The same value in `em` |
|
|
145
|
+
| Body `font-size` in `px` | `rem` |
|
|
146
|
+
| Weight `100`–`300` or `font-thin`, `font-light` on text under `18px` | `400` or heavier |
|
|
147
|
+
| `text-wrap: balance` on a paragraph | `text-wrap: pretty` |
|
|
148
|
+
| `text-align: justify` in application UI | `text-align: start` |
|
|
149
|
+
| `-webkit-line-clamp` without `display: -webkit-box` | Add `display: -webkit-box` and `-webkit-box-orient: vertical` |
|
|
150
|
+
| A timer, counter, price or numeric column without `tabular-nums` | `font-variant-numeric: tabular-nums` |
|
|
151
|
+
| `...`, `--` or a hyphenated range in rendered strings | `…`, an em dash or an en dash |
|
|
152
|
+
| `text-decoration-skip-ink: none` | Remove it; set `text-underline-offset` or `from-font` instead |
|
|
153
|
+
| `<input>` with `text-sm` or `14px` and no mobile override | One of the **Inputs at 16px on mobile** fixes |
|
|
154
|
+
| `-webkit-font-smoothing` or `antialiased` inside a component | Move it to the root |
|
|
155
|
+
| Mixed-direction value such as a name, number or URL without `<bdi>` or `dir` | Wrap it in `<bdi>` |
|
|
156
|
+
| `user-select: none` or `select-none` on a layout root or text container | Remove it; keep it only on a drag or gesture surface |
|
|
157
|
+
|
|
158
|
+
## Reporting
|
|
159
|
+
|
|
160
|
+
**Severity.** `HIGH` makes text unreadable, truncates content with no way back to it or clips text at 320px width or 200% zoom. The last two are `interface` escalation triggers, so they stay `HIGH` however minor the surface. `MEDIUM` breaks the type system or the visual heading hierarchy. `LOW` is isolated polish.
|
|
161
|
+
|
|
162
|
+
**Verification.** Without a browser, check declared size and weight per heading level, descending within each semantic section. Check declared line-height, units and measure. Check truncation rules against realistic string lengths. With one, compare computed values, then resize the viewport with real content to catch wrapping, lone last-line words and truncation. Report every check you could not run as `Not verified`.
|
|
163
|
+
|
|
164
|
+
**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
|
|
165
|
+
|
|
166
|
+
| Severity | Location | Before | After | Why |
|
|
167
|
+
| --- | --- | --- | --- | --- |
|
|
168
|
+
|
|
169
|
+
`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
|
|
170
|
+
|
|
171
|
+
End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable typography findings" and report verification.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Choosing fonts
|
|
2
|
+
|
|
3
|
+
Font categories, fallback stacks for a type change, file formats and why fonts look the way they do.
|
|
4
|
+
|
|
5
|
+
## Choosing a typeface
|
|
6
|
+
|
|
7
|
+
| Category | Traits | Use for |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| Serif | Small strokes at the ends of letters guide the eye along a line | Long passages, editorial reading |
|
|
10
|
+
| Sans-serif | Clean, even shapes that stay crisp at small sizes | Default for most interfaces (Helvetica, Inter, Geist) |
|
|
11
|
+
| Monospace | Every glyph the same width | Code and fixed-width identifiers; numeric columns use `tabular-nums` instead |
|
|
12
|
+
| Display | Drawn for large headlines | Marketing headlines, hero text |
|
|
13
|
+
| Script | Mimics handwriting | Rare, decorative moments |
|
|
14
|
+
|
|
15
|
+
"Display" in a font's name does not make it a display font. SF Pro and Heldane ship a `Display` variant for large sizes and a `Text` variant for small ones. Use the variant matching the size you are setting.
|
|
16
|
+
|
|
17
|
+
## Fallback stacks for a type change
|
|
18
|
+
|
|
19
|
+
When a type change is asked for, two routes. `system-ui` gives each operating system's own interface face. A commercial face such as Helvetica Now is a brand decision and still needs a fallback stack.
|
|
20
|
+
|
|
21
|
+
```css
|
|
22
|
+
/* The platform's native interface face */
|
|
23
|
+
html {
|
|
24
|
+
font-family: system-ui, sans-serif;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/* Commercial brand face with safe fallbacks */
|
|
28
|
+
html {
|
|
29
|
+
font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Formats
|
|
34
|
+
|
|
35
|
+
| Format | Notes |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `.woff2` | Brotli compression, broadly supported. Use this on the web. |
|
|
38
|
+
| `.woff` | Older compression. Fallback only for very old browsers. |
|
|
39
|
+
| `.ttf` / `.otf` | Desktop formats with no built-in compression, so larger files. Only when there is no other option. |
|
|
40
|
+
|
|
41
|
+
How the files load is the project's concern.
|
|
42
|
+
|
|
43
|
+
## Anatomy of a typeface
|
|
44
|
+
|
|
45
|
+
| Term | Meaning |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| x-height | Height of a lowercase `x` |
|
|
48
|
+
| Cap height | Height of uppercase letters |
|
|
49
|
+
| Baseline | The invisible line letters sit on |
|
|
50
|
+
| Ascender | Part of a letter rising above the x-height |
|
|
51
|
+
| Descender | Part dropping below the baseline |
|
|
52
|
+
|
|
53
|
+
These measurements are why two fonts at the same `font-size` look like different sizes. A large x-height looks bigger.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# CSS cheat sheet
|
|
2
|
+
|
|
3
|
+
One-line lookup for every typography CSS declaration covered by this skill, with the Tailwind 4 equivalent. Where no utility exists, the arbitrary-value form is shown. Pick the column that matches the project: the declaration in plain CSS, CSS Modules, styled-components or StyleX codebases, the utility in Tailwind codebases.
|
|
4
|
+
|
|
5
|
+
## Font
|
|
6
|
+
|
|
7
|
+
| Declaration | What it does | Tailwind |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `font-family: sans-serif` | The sans family | `font-sans` |
|
|
10
|
+
| `font-family: serif` | The serif family | `font-serif` |
|
|
11
|
+
| `font-family: monospace` | The monospace family | `font-mono` |
|
|
12
|
+
| `font-size` | Size from the type scale | `text-*` |
|
|
13
|
+
| `font-weight` | Any value from 1 to 1000 | `font-*` |
|
|
14
|
+
| `font-style: italic` | Switch to italic style | `italic` |
|
|
15
|
+
| `-webkit-font-smoothing` + `-moz-osx-font-smoothing` | Smooth macOS font rendering; apply once at the root | `antialiased` |
|
|
16
|
+
| `font-synthesis: none` | Disable all synthesized forms after verifying fallbacks and emphasis | `[font-synthesis:none]` |
|
|
17
|
+
| `font-feature-settings` | Toggle OpenType features | `[font-feature-settings:"ss01"]` |
|
|
18
|
+
| `font-variation-settings` | Tune variable font axes | `[font-variation-settings:"GRAD"_80]` |
|
|
19
|
+
| `font-optical-sizing: auto` | Optical size follows font size; the default, so leave it | none needed |
|
|
20
|
+
| `font-variant-caps` | Real small capitals | `[font-variant-caps:small-caps]` |
|
|
21
|
+
| `font-variant-position` | Real super and subscripts | `[font-variant-position:super]` |
|
|
22
|
+
| `font-variant-numeric: tabular-nums` | Equal-width digits | `tabular-nums` |
|
|
23
|
+
| `font-variant-numeric: slashed-zero` | Tell 0 from O | `slashed-zero` |
|
|
24
|
+
|
|
25
|
+
## Spacing and layout
|
|
26
|
+
|
|
27
|
+
| Declaration | What it does | Tailwind |
|
|
28
|
+
| --- | --- | --- |
|
|
29
|
+
| `letter-spacing` | Space between letters | `tracking-*` |
|
|
30
|
+
| `line-height` | Space between lines | `leading-*` |
|
|
31
|
+
| `font-kerning` | Kerning on or off | `[font-kerning:none]` |
|
|
32
|
+
| `text-box: trim-both` | Trim space above and below | `[text-box:trim-both_cap_alphabetic]` |
|
|
33
|
+
| `max-width` on text columns | Cap at ~60–75 characters per line | `max-w-xl` / `max-w-2xl` / `max-w-prose` |
|
|
34
|
+
| `text-align` | Where lines start and end | `text-start` / `text-center` |
|
|
35
|
+
|
|
36
|
+
## Wrapping and overflow
|
|
37
|
+
|
|
38
|
+
| Declaration | What it does | Tailwind |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| `text-wrap: balance` | Even out heading lines | `text-balance` |
|
|
41
|
+
| `text-wrap: pretty` | Keep a lone word off the last line | `text-pretty` |
|
|
42
|
+
| `text-overflow: ellipsis` | Ellipsis for clipped text | `text-ellipsis` |
|
|
43
|
+
| `overflow: hidden` + `text-overflow: ellipsis` + `white-space: nowrap` | Single-line truncation | `truncate` |
|
|
44
|
+
| `-webkit-line-clamp` + `display: -webkit-box` + `-webkit-box-orient: vertical` + `overflow: hidden` | Cut off after N lines | `line-clamp-*` |
|
|
45
|
+
| `overflow-wrap: break-word` | Break long strings | `break-words` |
|
|
46
|
+
| `white-space: nowrap` | Stop wrapping | `whitespace-nowrap` |
|
|
47
|
+
| `text-transform` | Change the casing | `uppercase` / `capitalize` |
|
|
48
|
+
| `hyphens: auto` | Hyphenate by the element's `lang` | `hyphens-auto` |
|
|
49
|
+
|
|
50
|
+
## Decoration and interaction
|
|
51
|
+
|
|
52
|
+
| Declaration | What it does | Tailwind |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| `text-decoration-line: underline` | Draw an underline | `underline` |
|
|
55
|
+
| `text-decoration-color` | Underline color | `decoration-*` |
|
|
56
|
+
| `text-decoration-thickness` | Underline thickness | `decoration-1` / `decoration-2` |
|
|
57
|
+
| `text-underline-offset` | Push the line down | `underline-offset-*` |
|
|
58
|
+
| `text-underline-position: from-font` | Underline position from the font | `[text-underline-position:from-font]` |
|
|
59
|
+
| `text-decoration-style` | Dotted, dashed or wavy | `decoration-dotted` / `decoration-wavy` |
|
|
60
|
+
| `text-decoration-thickness: from-font` | Underline set by the font | `decoration-from-font` |
|
|
61
|
+
| `text-decoration-skip-ink` | Gaps around descenders; `auto` is the default | `[text-decoration-skip-ink:auto]` |
|
|
62
|
+
| `caret-color` | Tint the text cursor | `caret-*` |
|
|
63
|
+
| `user-select: none` | Suppress selection on a verified drag/gesture conflict only | `select-none` |
|
|
64
|
+
| `text-shadow` | Shadow behind the letters | `text-shadow-*` |
|
|
65
|
+
| `-webkit-text-stroke` | Outline the letters | `[-webkit-text-stroke:1px_black]` |
|
|
66
|
+
| `background-clip: text` | Clip a background to the letters | `bg-clip-text` |
|
|
67
|
+
| `initial-letter` | Size a drop cap | `[initial-letter:3]` |
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Details and accessibility
|
|
2
|
+
|
|
3
|
+
Underlines, selection, form text and decorative text.
|
|
4
|
+
|
|
5
|
+
## Underlines
|
|
6
|
+
|
|
7
|
+
From the font's own metrics:
|
|
8
|
+
|
|
9
|
+
```css
|
|
10
|
+
a {
|
|
11
|
+
text-underline-position: from-font;
|
|
12
|
+
text-decoration-thickness: from-font;
|
|
13
|
+
}
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
A dotted underline on an abbreviation:
|
|
17
|
+
|
|
18
|
+
```css
|
|
19
|
+
abbr {
|
|
20
|
+
text-decoration: underline dotted;
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Or tune manually:
|
|
25
|
+
|
|
26
|
+
```css
|
|
27
|
+
a {
|
|
28
|
+
text-decoration-thickness: 1px;
|
|
29
|
+
text-underline-offset: 3px;
|
|
30
|
+
text-decoration-color: var(--color-gray-1000);
|
|
31
|
+
transition: text-decoration-color 200ms ease-out;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
a:hover {
|
|
35
|
+
text-decoration-color: var(--color-gray-1200);
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Selection
|
|
40
|
+
|
|
41
|
+
- `::target-text` styles the phrase a shared link scrolls to.
|
|
42
|
+
- The Custom Highlight API styles ranges you pick yourself, like search matches, without extra markup.
|
|
43
|
+
|
|
44
|
+
## Forms and editable text
|
|
45
|
+
|
|
46
|
+
- `::placeholder` styles the hint in an empty field.
|
|
47
|
+
- `caret-color` colors the blinking insertion bar. A fully custom caret is hard to build and rarely worth it.
|
|
48
|
+
|
|
49
|
+
### iOS input zoom
|
|
50
|
+
|
|
51
|
+
**Size up on mobile.** The input renders at `16px` on small screens and drops to the design size from the `sm` breakpoint up. Nothing to compensate, but the mobile input no longer matches the desktop one.
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
<input className="text-base sm:text-sm" type="email" />
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**Scale the text down.** Keep `font-size` at `16px` so Safari never zooms, then render at the intended size with a transform. Widen the element by the inverse of the scale so it still fills its container once shrunk. Divide `line-height` by the same factor so the intended leading survives. `origin-left` pins the text to the start edge, `origin-right` under RTL. Above the breakpoint, drop the transform and set the real size.
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
// 13px rendered from a 16px font-size: 13 / 16 = 0.8125
|
|
61
|
+
<div className="flex h-10 items-center overflow-hidden rounded-[10px] bg-gray-300 px-2.5 focus-within:outline focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-blue-500">
|
|
62
|
+
<input
|
|
63
|
+
className="h-full w-[calc(100%/0.8125)] shrink-0 origin-left rtl:origin-right scale-[0.8125] bg-transparent text-base leading-[calc(1.125/0.8125)] outline-none sm:w-full sm:scale-100 sm:text-[13px]"
|
|
64
|
+
type="email"
|
|
65
|
+
/>
|
|
66
|
+
</div>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`shrink-0` preserves the compensated width inside the flex wrapper. The wrapper clips the oversized layout box and draws an unscaled focus outline. Use the project's focus color and verify its contrast against the surrounding surface.
|
|
70
|
+
|
|
71
|
+
The transform shrinks the whole box, not only the glyphs, so let a wrapper draw the field's surface and keep the input transparent. A background, border or ring on the scaled element shrinks with the text and misses the intended hit area.
|
|
72
|
+
|
|
73
|
+
## Decorative text
|
|
74
|
+
|
|
75
|
+
| Property | Effect |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `::first-letter` | Drop cap, widely supported |
|
|
78
|
+
| `::first-line` | Styles only the first line |
|
|
79
|
+
| `initial-letter` | Sizes the drop cap; Safari needs `-webkit-initial-letter`, no Firefox yet |
|
|
80
|
+
| `background-clip: text` | Clips a background or gradient to the letter shapes |
|
|
81
|
+
| `-webkit-text-stroke` | Outlines the letters; works across modern browsers despite the prefix |
|
|
82
|
+
| `text-shadow` | Like `box-shadow` but follows the character shapes |
|
|
83
|
+
|
|
84
|
+
If `-webkit-text-stroke` draws lines inside the letters, the font has overlapping contours. Variable fonts often keep them unmerged, so use the static cut for stroked text.
|