/* ========================================================================= surface-treatments — separate surfaces composed from three axes; the disclosure; content emphasis. An OPT-IN VISUAL RULE under Foundations. It owns PRESENTATION ONLY: no markup, no semantics, no template, and no generated preview. A consuming surface writes its own markup and applies these classes to it. It serves BOTH lifecycles. A live surface references or vendors it and re-syncs when it changes. An artifact scaffold may inline it at generation time, after which the sealed copy does not re-sync. It loads no resource and imports no stylesheet, so it inlines verbatim — together with surface-panel.css, which it extends. LOAD ORDER colors_and_type.css -> surface-panel.css -> surface-treatments.css (surface-document.css, where a page also uses it, loads before this file) LOAD ORDER IS LOAD-BEARING. 1 surface-panel.css comes first. It authors the glass recipe once and shares it by selector grouping: .surface-material-page, .surface-material-panel, .surface-attach-free and .surface-elevation-raised are defined THERE. Without that file those four classes do nothing. 2 Material and elevation precede emphasis. The emphasis border and paint then win at equal specificity (0,1,0) over a material's edge and over .surface-elevation-flush. 3 .surface-emphasis.surface-elevation-raised composes the emphasis paint with the raised shadow at (0,2,0), so an emphasized surface that is also raised keeps both. It names --shadow-md again, because a box-shadow list cannot compose across rules. 4 The accent modifiers follow the base rules that set a default accent. 5 The disclosure's foreground rules share one specificity per host — (0,3,1) for the indicator and (0,2,1) for the summary of a details host; (0,3,0) and (0,2,0) for a controlled trigger — and are ordered [open] / [aria-expanded="true"] < :hover < :focus-visible, so a trigger that is hovered and focused shows the focus signal: the magenta indicator and the outline. USE. Use .surface-panel for a live content panel, and always for a panel that is itself a link: a.surface-panel is the only linked-panel form. Use .surface-separate plus one material, one attachment and one elevation where the reader needs a separate plane that is not a content panel — an emphasis panel or a comparison plane. Never compose axis classes or .surface-emphasis onto .surface-panel: this file loads later, so either would silently replace part of the panel. This module offers no emphasis for a full-panel link; the repository README (Hover, press, focus) records that a persistent emphasis on one is overwritten while it is hovered or focused and needs the consumer's own composition. It introduces no token and no palette value. Space, type, color, radius, motion and shadow resolve through the foundation, apart from the registered literals below. There is no blur here and no blur token: the one value every blurring material uses is the panel recipe's, authored in surface-panel.css. CATALOG SURFACE AXES meaning a separate surface selected on three independent axes: material (fill, blur, edge), attachment (corners) and elevation (depth cue); none determines another population a separate plane that is not a content panel: an emphasis panel, a comparison plane, a section synthesis (surface-document.css: panel material, free, flush), an overlay or an independently scrolling region owner this module; the page material, panel material, free attachment and raised elevation are authored in surface-panel.css and shared by selector grouping reuses --surface-glass, --line-1, --radius-lg, --radius-pill, --shadow-md, --space-5 variation material page | panel · attachment free | top | bottom | full-width | chip · elevation flush | raised exclusions content panels take .surface-panel; ordinary flow, subordinate grouping and quotation take no surface example a flush emphasis plane on the page material with free corners counterexample a raised, blurred card wrapped around an ordinary subsection ATTACHMENT meaning which edges a surface is joined to; it governs CORNER TREATMENT ONLY — radius on the free corners, none where every edge is joined population free-standing surfaces; surfaces joined at the top or the bottom edge; surfaces joined along their full width; chips owner this module reuses --radius-lg, --radius-pill variation .surface-attach-free · .surface-attach-top (hangs from the top: the bottom corners round) · .surface-attach-bottom (rises from the bottom: the top corners round) · .surface-attach-full-width (no corner rounds) · .surface-attach-chip (pill corners) exclusions no fill, blur, edge or shadow; an attached surface here keeps all four edges. surface-shell's navigation panel realizes the same corner rule pattern-locally and also drops the border on its joined edge; it does not consume these classes example a drawer hanging from the top edge rounds its two bottom corners, whatever its material and elevation counterexample a full radius on that drawer, which rounds a joined edge and detaches it from what it hangs from DISCLOSURE meaning a trigger and the region it expands population a details element whose summary names what it reveals; or, where the host must keep a region it controls, a button carrying .surface-disclosure-trigger whose aria-expanded and aria-controls state that region. The controlled trigger takes the summary's grammar — label, indicator, rotation, hover and focus — and none of the enclosure's geometry: its host keeps padding, placement and the region's own surface owner this module reuses the panel material, free attachment and flush elevation for its enclosure; operative-label metrics for the trigger; --space-6 inset, --space-4 gap; --fg-1 at 2px, --space-1 out, for the trigger's keyboard-focus outline variation none per artifact exclusions the region takes no second surface; the trigger joins neither the attention edge nor the foreground-bound link treatment: its hover and focus are its own example a census kept behind a "measured census" trigger; a diagram's legend behind a "legend" trigger on a small canvas counterexample a summary styled as a compact action, or a heading standing in for the trigger; a plus or minus sign standing in for the indicator CONTENT EMPHASIS meaning "this deserves attention": persistent, assigned by the content's role, and not interactive. It is not elevation, not containment and not interaction — hover and focus are transient and border-only; emphasis stays at rest population .surface-emphasis for a whole unit (a perimeter and a soft bloom, present at rest); .surface-emphasis-rail for a bounded passage in the reading flow (a vertical accent rule and an inset), which in a document is the authorial callout; .surface-emphasis-chip for the marker that names why — on a surface with no accent of its own, such as a section synthesis panel, the chip carries the accent modifier itself, so only its border takes the accent and the panel gains no perimeter and no bloom owner this module reuses --ask-emphasis-magenta, --ask-emphasis-violet, --ask-emphasis-cyan; operative-label metrics for the chip; --fg-1 for the chip's words variation the accent (.surface-emphasis--magenta | --violet | --cyan) supplied by the content's role; the dose per theme exclusions no hover, press, focus or animation; the chip's words stay in the primary text role and the accent stays on the border; use the least elaborate treatment that expresses the distinction example a finding marked "read this first", its accent on the perimeter and the chip border counterexample a hard directional drop shadow with no visible border, or chip words set in the accent THE EMPHASIS DOSE. The themes are deliberately not numerically equal, because equal numbers do not read as equal emphasis: light has an apparent 1.5px edge (the 1px border plus a 0.5px zero-blur ring, which grows the edge without growing layout) and a 28% bloom; dark has a 1px edge and a 50% bloom. The dark dose applies under an explicit dark theme, a .theme-dark subtree and an automatic dark theme. REGISTERED LITERALS — no token expresses these values 1px, 2px surface edge and accent-rail widths 0.5px, 0 the emphasis ring, light and dark 28%, 50% the emphasis bloom alpha, light and dark 70% the emphasis ring's accent mix 22px 1px the emphasis bloom's blur and spread -90deg the closed disclosure indicator's rotation 1 the disclosure indicator's leading 2px the emphasis chip's block padding 2px the disclosure trigger's focus-outline width LIMITS - Hover and focus colors on the disclosure trigger depend on the source order stated above; a consumer that restates one of them restates all three in the same order. - Under prefers-reduced-motion: reduce the indicator changes state without animating. - The trigger's focus outline is drawn --space-1 outside the summary, inside the disclosure's --space-6 inset; a consumer that clips that band hides it. ========================================================================= */ /* ---- Surface axes ----------------------------------------------------- */ /* Material, free attachment and raised elevation are authored in surface-panel.css. What follows is what the panel recipe does not select. */ /* ATTACHMENT — corners only. */ .surface-attach-top { border-radius: 0 0 var(--radius-lg) var(--radius-lg); } .surface-attach-bottom { border-radius: var(--radius-lg) var(--radius-lg) 0 0; } .surface-attach-full-width { border-radius: 0; } .surface-attach-chip { border-radius: var(--radius-pill); } /* ELEVATION — flush. Absence of a shadow is not deficient elevation. */ .surface-elevation-flush { box-shadow: none; } /* A SEPARATE SURFACE — the plane itself. Its material, attachment and elevation are chosen with the axis classes above. */ .surface-separate { padding: var(--space-5); } /* ---- Disclosure ------------------------------------------------------- */ /* The enclosure composes the axes: .surface-disclosure + .surface-material-panel + .surface-attach-free + .surface-elevation-flush. */ .surface-disclosure { display: flex; flex-direction: column; gap: var(--space-4); padding: var(--space-6); } /* The trigger's grammar, shared by the summary of a details host and a controlled trigger. */ .surface-disclosure > summary, .surface-disclosure-trigger { cursor: pointer; font-family: var(--font-mono); font-size: var(--fs-caption); font-weight: var(--fw-light); letter-spacing: var(--tracking-wide); text-transform: uppercase; color: var(--fg-2); } .surface-disclosure > summary { list-style: none; margin: 0; display: flex; align-items: center; justify-content: space-between; gap: var(--space-3); } /* A controlled trigger is a native button: its own chrome is reset, and its host supplies any surface around it. */ .surface-disclosure-trigger { appearance: none; margin: 0; padding: 0; border: 0; background: none; display: inline-flex; align-items: center; gap: var(--space-3); text-align: start; } .surface-disclosure-trigger > .surface-disclosure-label { flex: 0 1 auto; min-width: 0; } .surface-disclosure > summary::-webkit-details-marker { display: none; } /* The label is a real flex item so a long label can shrink and wrap. It shrinks and does not grow: justify-content already places the indicator at the trailing edge. */ .surface-disclosure > summary > .surface-disclosure-label { flex: 0 1 auto; min-width: 0; } .surface-disclosure[open] > summary { color: var(--fg-1); } .surface-disclosure > summary .surface-disclosure-indicator, .surface-disclosure-trigger .surface-disclosure-indicator { flex: 0 0 auto; font-size: var(--fs-caption); line-height: 1; color: var(--fg-2); transition: transform var(--dur-2) var(--ease-out); } .surface-disclosure[open] > summary .surface-disclosure-indicator { color: var(--fg-1); } .surface-disclosure:not([open]) > summary .surface-disclosure-indicator { transform: rotate(-90deg); } /* The controlled trigger reads its state from aria-expanded, the one truthful source its controller keeps. */ .surface-disclosure-trigger[aria-expanded="true"] { color: var(--fg-1); } .surface-disclosure-trigger[aria-expanded="true"] .surface-disclosure-indicator { color: var(--fg-1); } .surface-disclosure-trigger[aria-expanded="false"] .surface-disclosure-indicator { transform: rotate(-90deg); } /* Hover: a closed disclosure's foreground rises; an open one already rests at --fg-1. No border, no opacity drop, no press. */ .surface-disclosure > summary:hover { color: var(--fg-1); } .surface-disclosure > summary:hover .surface-disclosure-indicator { color: var(--fg-1); } .surface-disclosure-trigger:hover { color: var(--fg-1); } .surface-disclosure-trigger:hover .surface-disclosure-indicator { color: var(--fg-1); } /* Focus: the summary is at --fg-1, the indicator takes the emphasis magenta and a 2px --fg-1 outline surrounds the trigger, --space-1 out. The outline is the signal that always shows: an open disclosure's summary already rests at --fg-1, and a trigger may lead with a mark that keeps its own color. These follow the hover rules on purpose (load order, item 5). */ .surface-disclosure > summary:focus-visible { color: var(--fg-1); outline: 2px solid var(--fg-1); outline-offset: var(--space-1); } .surface-disclosure > summary:focus-visible .surface-disclosure-indicator { color: var(--ask-emphasis-magenta); } .surface-disclosure-trigger:focus-visible { color: var(--fg-1); outline: 2px solid var(--fg-1); outline-offset: var(--space-1); } .surface-disclosure-trigger:focus-visible .surface-disclosure-indicator { color: var(--ask-emphasis-magenta); } .surface-disclosure > .surface-disclosure-body { margin: 0; } @media (prefers-reduced-motion: reduce) { .surface-disclosure > summary .surface-disclosure-indicator, .surface-disclosure-trigger .surface-disclosure-indicator { transition: none; } } /* ---- Content emphasis ------------------------------------------------- */ /* The rail: a bounded passage inside the reading flow or inside an existing surface. No perimeter, no bloom, no second wash. It marks attention, not a change of voice, so it is not quotation. In a document it is the authorial callout: a thesis, posed question or contrast the document states in its own voice (surface-document.css). surface-document.css reuses its geometry — width, style and inset — for the passage rail of a quotation and a preformatted block, but not its meaning: a quotation's rail is violet, represented voice, and a preformatted block's is magenta like this one. check-type-roles.mjs (R7) keeps the geometry equal and pins each color. On document text this rail is always magenta; elsewhere the violet and cyan modifiers below stay valid. Where surface-document.css is loaded, a rail inside a railed passage — a quotation, a block or another rail — draws none: that module's nested-rail rule removes it, so one passage keeps one rail. */ .surface-emphasis-rail { --surface-emphasis-accent: var(--ask-emphasis-magenta); border-left: 2px solid var(--surface-emphasis-accent); padding-left: var(--space-4); } /* Two rails in a row would read as one passage. A rail directly after a rail takes a buffer, added to whatever gap its parent supplies. */ .surface-emphasis-rail + .surface-emphasis-rail { margin-top: var(--space-5); } /* The dose, per theme. */ :root { --surface-emphasis-ring: 0.5px; --surface-emphasis-bloom: 28%; } :root[data-theme="dark"], .theme-dark { --surface-emphasis-ring: 0; --surface-emphasis-bloom: 50%; } :root[data-theme="light"] { --surface-emphasis-ring: 0.5px; --surface-emphasis-bloom: 28%; } @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --surface-emphasis-ring: 0; --surface-emphasis-bloom: 50%; } } /* The panel: a perimeter plus a soft bloom, present at rest. Flush by default: an emphasized unit must be easier to notice, not necessarily higher. */ .surface-emphasis { --surface-emphasis-accent: var(--ask-emphasis-magenta); border: 1px solid var(--surface-emphasis-accent); box-shadow: 0 0 0 var(--surface-emphasis-ring) color-mix(in srgb, var(--surface-emphasis-accent) 70%, transparent), 0 0 22px 1px color-mix(in srgb, var(--surface-emphasis-accent) var(--surface-emphasis-bloom), transparent); } /* Emphasis and elevation are separate axes: a raised emphasized surface keeps both rather than one replacing the other. */ .surface-emphasis.surface-elevation-raised { box-shadow: 0 0 0 var(--surface-emphasis-ring) color-mix(in srgb, var(--surface-emphasis-accent) 70%, transparent), 0 0 22px 1px color-mix(in srgb, var(--surface-emphasis-accent) var(--surface-emphasis-bloom), transparent), var(--shadow-md); } /* The accent is supplied by the content's role, never chosen decoratively. These bind the existing emphasis accents and create none. */ .surface-emphasis--magenta { --surface-emphasis-accent: var(--ask-emphasis-magenta); } .surface-emphasis--violet { --surface-emphasis-accent: var(--ask-emphasis-violet); } .surface-emphasis--cyan { --surface-emphasis-accent: var(--ask-emphasis-cyan); } /* The marker that names why a unit is emphasized. Two channels on purpose: the accent arrives on the border, where it cannot drift from the perimeter it belongs to, and the words are set in the primary text role. Outside an accented surface the border falls back to the tertiary foreground. */ .surface-emphasis-chip { display: inline-block; align-self: flex-start; font-family: var(--font-mono); font-size: var(--fs-caption); font-weight: var(--fw-light); line-height: var(--lh-tight); letter-spacing: var(--tracking-wide); text-transform: uppercase; color: var(--fg-1); border: 1px solid var(--surface-emphasis-accent, var(--fg-3)); border-radius: var(--radius-sm); padding: 2px var(--space-2); margin: 0; } /* Inline emphasis inside the trigger and the chip. Scoped, so strong and em elsewhere keep their own styling. */ :where(.surface-disclosure, .surface-emphasis-chip) strong { font-weight: var(--fw-medium); color: var(--fg-1); } :where(.surface-disclosure, .surface-emphasis-chip) em { font-style: italic; }