# Pattern // surface shell The shared page shell for a family of public surfaces. --- ## What this pattern is One page composition, applied across a family of surfaces so they read as one artifact family with different payloads rather than as separate sites. The shell carries an identity-mark slot, the surface identity, a lede, an optional status badge, an optional payload control slot, the rule that closes the header, and the footer that closes the page. `surface-shell` is an **ASK-family pattern**. It inherits the shared Tier-1 foundations and the Tier-2 design language — role tokens, typography, spacing, palette discipline, motion, and the interaction grammar — and it hard-codes no consuming surface's **Tier-3** identity. Tier-3-neutral is not ASK-neutral: a consumer adopting this pattern is adopting the ASK design language, and supplies only its own Tier 3. `design-system-ASK`'s own pages are its first consumers, not its required identity. "Its own" means locally supplied by the consumer's source of intent — not necessarily a distinct mark. ASK may assign the ASK wordmark to an ASK-family project; the shell still ships no mark, makes no assignment, and does not make that project ASK-the-entity. The shell owns the chrome around the payload. It owns no payload. A consuming surface supplies everything between the rule and the footer, the footer's own destinations, and its own Tier 3 identity. The header is flush left and the footer is flush right. That pairing is the shell's, not a per-surface preference: the reader's eye travels top-left to bottom-right, so the page opens where reading starts and closes where reading ends. A left-aligned footer restarts the eye in a column the page has already finished with. Do not re-align either one locally. This is a **surface pattern**, not Class A and not Class B. Class A templates render diagrams; Class B templates seal project-output artifacts. This one frames a live public page and seals nothing. It is catalogued in its own group for that reason. Do not file it under an existing class, and do not read a new class label into it — one surface pattern does not earn a taxonomy. --- ## Files | File | What it is | | --- | --- | | `surface-shell.css` | The canonical implementation. Composes existing `var()` roles; defines no token. | | `surface-shell.template.html` | The canonical markup specimen, with the required structure and both optional slots. | | `surface-shell.js` | **Optional** responsive-navigation runtime. Vendored only by surfaces that adopt navigation. | The rendered specimen is generated to `patterns/_preview/surface-shell.html` by `tools/gen-pattern-previews.mjs`. It is owner preview evidence — do not vendor it. **What to vendor.** The core shell is `surface-shell.css` plus the template, and every consumer takes those. Two additions are conditional, and they are separate questions: | Also vendor | When | | --- | --- | | `surface-action.css` (repo root) | The surface renders **footer destinations**, **or** adopts navigation. | | `surface-shell.js` (this directory) | The surface **adopts navigation**. A declining surface ships no copy. | **Navigation requires `surface-action.css` on its own**, whether or not the surface has a footer to style. The panel's **close control is mandatory** and is a compact action — the runtime builds it for every adopter — while the utility row is optional. A surface that adopts navigation, has no footer destinations, omits the utility row, and follows these instructions to the letter would otherwise ship an unstyled mandatory button. `surface-action.css` sits beside the vendored shell, referenced by bare filename, exactly as the template does. It is **not** a `_dsa-tokens/` file: that mirror is for tokens and fonts, and routing a visual module through it would make a convenient path into a false architecture. CSS pins are tracked for every consumer; the JS pin only for adopters. --- ## Required markup ```html

[org] [repo]

…

…payload…
``` The `.surface-mark` wrapper above is the **non-interactive** form, which is the right one only where the surface has no home destination and adopts no navigation. Everywhere else the wrapper itself becomes the link — ``, with no `role="img"`. Both forms are specified under §The identity mark. ### The structural title, and its two variants The title is a locator, not a display heading, and every structural separator is `//` — never a single slash. Each separator is a decorative `

` wrapped in a breadcrumb landmark | A **real** ancestor is one with a public destination a reader can actually reach. An ancestor that exists only as a concept, or whose page is not public, is not one, and inventing a destination to manufacture a segment is the failure this rule guards against — not the absence of one. The distinction is deliberately **not** "inside this surface's own family". A project root with a genuine public parent above it — a studio route above a project, an organization above a studio — *has* ancestry, and hiding it makes the same surface announce a different depth depending on which family happens to own it. A reader crossing between two of a studio's projects should meet one hierarchy, not two dialects of one. > **This supersedes an earlier rule.** Before this change the pattern said a > root-level surface kept a plain title even when its `.org` segment linked > outward, on the reasoning that one outward link does not make a surface a > subpage *of its own family*. That is true and no longer the test: the crumb > describes public ancestry, and a real public parent is ancestry. The > design-system's own root page was the named example, and it is now a > breadcrumb. **A breadcrumbed title.** Linkability is decided by **destination, not by segment class** — the class names what a segment *is*, never whether it has somewhere to go: | segment | treatment | | --- | --- | | a real ancestor or home destination | linked | | structural context with no destination of its own | static | | the current segment | unlinked, with `aria-current="page"` | The classes say nothing about what kind of thing a segment names, and **they do not share a scope** — one is available to both title forms and one is not: | class | plain title | breadcrumbed title | | --- | --- | --- | | `.org` | the static owning context | the outermost ancestry segment | | *(none)* | the local current surface label | an intermediate ancestor | | `.page` | — | the inert current leaf, **at any depth in the path** | `.org` is **valid in both forms**, which is why the generic plain specimen carries `[org]`. Only `.page` and the intermediate reading of an unclassed segment belong to a breadcrumb path, because only a path has depth to grade. `.page` is the *current* segment, not a "payload" one. A family root that is the page you are on takes it, exactly as a deep subpage does — which is why the design-system's own front door carries `design-system-ASK`. There is no root-page exception, because an exception is precisely what would reintroduce two grammars. **Currentness and linkability are different axes, and the table above grades only the first.** A current leaf carries no `href` *because* it is current — that is a consequence of being current, never the reason it takes `.page`. Never omit `.page` from a breadcrumb leaf on the ground that it has no destination, and never promote ordinary static context to `.page` merely because it also lacks one. **A plain title's local label is unclassed because the plain form carries no breadcrumb path** — not because classes are unavailable to it, and not because the label has no destination. That is a distinction between the two *title forms*, and it is not a licence to leave a breadcrumbed family root's leaf bare. Never invent a destination to make a segment interactive. The generic form below leaves `[org]` static, because a placeholder organization has no destination to link to. That is the *placeholder's* topology, not a default — an organization segment is static only while it genuinely has nowhere to go: ```html ``` **design-system-ASK's own surfaces are the linked case**, and they are worth reading against the generic form above. Every ancestor above them is real and public, so every one of them appears: ```html ASK apex solar kiss design-system-ASK style guide ``` Two details there are consumer topology rather than pattern rule, and a different consumer will resolve them differently. The **human-facing brand name** is the label — `apex solar kiss`, not the `apexSolarKiss` GitHub handle, because a breadcrumb names a place a reader goes rather than a repository namespace. And **within this breadcrumb path the segment classes grade depth**: `.org` on the outermost ancestor, `.page` on the inert current leaf, nothing on the segments between. That grading is what lets a four-segment chain still read as one object rather than four equal words. A plain title has no path to grade, so it has no intermediate tier and no `.page` — it still carries `.org` for its owning context. The public IA parent is the destination, not the code host: a GitHub organization is a **utility** destination and belongs in the navigation panel, never in the breadcrumb's ancestry. Both forms are conformant, and the difference is topology rather than class. The `nav` wraps the title only — never the mark, never the lede. `nav` inside `

` would be invalid, since a heading takes phrasing content; wrapping is the valid arrangement and keeps the heading exposed as a heading. **Ancestor links wrap, so their press is non-geometric.** The repo's default press is `transform: scale(0.97)`, which needs a transformable box. Giving a breadcrumb link that box makes it shrink-to-fit: an ancestor wider than the content column stops breaking into inline fragments, fills the whole column, wraps inside itself, adds a line to the header, and draws its underline across the column rather than under the words. So these links keep ordinary inline wrapping and take the non-geometric limbs — opacity and underline — instead: | State | Opacity | Underline | | --- | --- | --- | | rest | 1 | `--surface-shell-link-underline` — the emphasis accent at 50% opacity | | hover | 1 | `--ask-emphasis-magenta` at full opacity | | active | 0.92 | `--ask-emphasis-magenta` at full opacity | The underline is a **text decoration**, not a border. It was a 1px `--line-2` border measuring 1.11:1 and 1.08:1 against the light gradient stops — texture rather than information — brightening only to 1.26:1 on hover. The new resting value is the accent's own hue at half dose, **not** a mix toward the foreground: mixing changes what color it is, and the resulting plum reads as a darker text color rather than a quieter magenta. It measures 1.72:1 / 1.82:1 light and 2.11:1 / 2.23:1 dark, so it does **not** clear the strict 3:1 non-text floor in either theme, and no strict AA claim is made for it. In light that floor is unreachable by any opacity; in dark a higher one would reach it, but that would be a different treatment from the single uniform default. The affordance rests on the **presence** of a rule where the surrounding text has none, plus an independently governed focus indicator. `surface-text-link.css` carries the full disposition. Hover spends the brightening limb; press adds the opacity drop on top of the already-bright underline. The `:hover` opacity declaration is an override: the foundation binds `a:hover { opacity: 0.92 }`, which would otherwise make hover and press compute identically. Declaring it inside `.surface-title` settles it on specificity rather than on stylesheet order. The foundation rule is unchanged. No state changes display, box construction, line breaking, measured width, or fragment count. **Focus is a text-decoration underline here, because this link fragments.** Anything drawn around the *box* fails on fragmented inline text. A `box-shadow` ring sliced — the default — is drawn around the unbroken box and then cut, so it opens on the cut edges. Cloned, each fragment closes, but the result is one ring per line rather than a single typographic indicator. A rectangular outline is a single shape only where consecutive fragments overlap horizontally, which is a property of where the text happens to break, not of the treatment: at a 256px column the break is `asymptotic` / `system key` and it is one shape; at 311px it is `asymptotic system` / `key` and it splits into one ring per line. All three were rendered before the rule was chosen. A text decoration is fragment-native — it follows each line's own text — so the indicator is: ```css .surface-title a:focus-visible { outline: none; box-shadow: none; text-decoration-color: var(--fg-1); text-decoration-thickness: 2px; text-underline-offset: 2px; } ``` The rest state is **also** a text decoration, so focus recolors and thickens the single decoration already there rather than clearing a competing one. Exactly one underline renders in every state, and nothing reflows because only color, thickness and offset change. `--fg-1` is the existing theme-resolving default foreground role: no new token, no `--fg-high-contrast` registration, and the same treatment on the quieter `.org` home link as on an ordinary ancestor. **Fragment-native and box indicators are not interchangeable.** A fragmenting inline link cannot carry a ring; a box can. Do not describe one anatomy across both: | Role | Focus indicator | Rest underline during focus | | --- | --- | --- | | `.surface-title a` (breadcrumb) | the same decoration, recolored to `--fg-1` at 2px / 2px | becomes the indicator | | `.surface-text-link` (module) | `--fg-1` decoration at 2px / 2px | becomes the indicator | | the identity mark | the white `box-shadow` ring | n/a | | footer destinations | `surface-action.css`'s attention edge, shared with its hover | n/a — they carry no underline | Two properties are worth naming so they are not mistaken for defects. `text-decoration-skip-ink` stays at its initial `auto`, so the underline breaks around descenders — per-glyph typographic clearance, not a contour opening at a line break. And `:focus-visible` is last among the equal-specificity state rules, so while a link is focused its underline *is* the focus indicator and the hover and active magenta limbs are suppressed; active still dims the whole element, because the focus rule sets no opacity. Measured at 320 / 360 / 375 / 393 / 414px in both themes: | Property | Result | | --- | --- | | every fragment carries the indicator | yes, at every width | | indicator pixels landing on neighboring glyph ink | 0 | | contrast against the light gradient stops | 3.50:1 · 4.00:1 | | contrast against the dark gradient stops | 10.25:1 · 12.26:1 | | fragment count, line breaks, width, title and header height, page overflow | identical focused and unfocused | The identity mark does not fragment and keeps the box-shadow glow. Footer destinations take `surface-action.css`'s attention edge — a magenta border, with a 0.5px ring in light only — not this pattern's. This is a surface-pattern exception for wrapping text, not a general retirement of press feedback. The identity mark is a block-level slot, and a footer destination is a compact action with a box of its own, so both are objects a transform can act on rather than inline text that fragments; both keep the scale press — the footer's now through `surface-action.css` rather than through a rule of the shell's. The `.org` span carries the owning organization; the `.page` span carries the current segment and takes `aria-current="page"`. The root variant omits `.page` because it has no navigable ancestor, not because the consumer has one surface. Either of `.org` and the repo segment may be a link or static — apply the destination test above to each, per surface. ### The lede One or two calm declarative sentences about the surface. The shell sets the foundation's **Small supporting-text role — 18px / 300** — and imposes **no measure**, so the lede uses the full header width that `.surface-head-main` grows into. A per-surface measure is the consuming surface's call. Implementation detail belongs in the payload. The lede is **not** Caption text. Caption is the 14px uppercase label role: the `.caption` utility sets 400 weight, 0.14em tracking, and uppercase over the foundation's inherited Inter. The lede is prose a reader reads, so it sits on the supporting-text step instead. The shell **footer** sits on no type step of its own, because it declares no type. Its destinations **are compact actions**, and `surface-action.css` owns their family, size, weight, tracking, padding, radius, fill, border, foreground, hover, press and focus: ```html ``` **They stay anchors.** A destination is navigation; a `