@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/heading.md

@@ -0,0 +1,189 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: heading
+  sourceFile: packages/design-system/src/components/heading.tsx
+  client: false
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Heading
+      kind: component
+      typeText: "ForwardRefExoticComponent<HeadingProps & RefAttributes<HTMLHeadingElement>>"
+    - name: HeadingAlign
+      kind: type
+    - name: HeadingAs
+      kind: type
+    - name: HeadingColor
+      kind: type
+    - name: HeadingProps
+      kind: type
+    - name: HeadingSize
+      kind: type
+    - name: headingVariants
+      kind: variants
+      typeText: "TVReturnType<{ size: { \"display-2xl\": \"ax:t-display-2xl\"; \"display-xl\": \"ax:t-display-xl\"; \"display-lg\": \"ax:t-display-lg\"; \"display-md\": \"ax:t-display-md\"; \"display-sm\": \"ax:t-display-sm\"; h1: \"ax:t-h1\"; ... 4 more ...;...[truncated]"
+    - name: HeadingWrap
+      kind: type
+  primaryExport: Heading
+  subcomponents: []
+  props:
+    Heading:
+      - name: align
+        type: "\"center\" | \"left\" | \"right\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: as
+        type: HeadingAs
+        required: false
+        declaredIn: self
+        doc: "The heading level, chosen for document outline. Defaults to `h2`."
+      - name: color
+        type: "\"default\" | \"muted\" | \"primary\" | \"strong\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: size
+        type: "\"display-2xl\" | \"display-lg\" | \"display-md\" | \"display-sm\" | \"display-xl\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: truncate
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: wrap
+        type: "\"balance\" | \"pretty\" | \"wrap\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLHeadingElement>, \"color\">"
+    - "VariantProps<typeof headingVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - display-2xl
+        - display-xl
+        - display-lg
+        - display-md
+        - display-sm
+        - h1
+        - h2
+        - h3
+        - h4
+        - h5
+        - h6
+      default: null
+      on: Heading
+    color:
+      kind: enum
+      options:
+        - default
+        - strong
+        - muted
+        - primary
+      default: default
+      on: Heading
+    align:
+      kind: enum
+      options:
+        - left
+        - center
+        - right
+      default: null
+      on: Heading
+    wrap:
+      kind: enum
+      options:
+        - wrap
+        - balance
+        - pretty
+      default: null
+      on: Heading
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-heading--default
+    - exportName: LevelDiffersFromSize
+      id: components-heading--level-differs-from-size
+    - exportName: Scale
+      id: components-heading--scale
+  storybookTitle: Components/Heading
+  docsId: components-heading--documentation
+  argTypeOptions:
+    as:
+      - h1
+      - h2
+      - h3
+      - h4
+      - h5
+      - h6
+    color:
+      - default
+      - strong
+      - muted
+      - primary
+  resolvedCleanly: true
+  contractHash: "00b98cc74dc9"
+  factsHash: e6283d313819
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Semantic h1-h6 heading whose level and visual size are set independently, on the canonical t-* heading and display scale."
+useWhen:
+  - "any heading in a screen, card, dialog or section that is not the page's top header row"
+  - "the document outline needs one level but the design calls for another size, e.g. an h1 that reads at h3 size"
+useInstead:
+  - id: page-header
+    when: "it is the top-of-page title row with a subtitle and actions"
+  - id: text
+    when: "the text is not a heading"
+related:
+  - text
+  - page-header
+  - empty-state
+a11y:
+  notes:
+    - "as sets the real heading level and therefore the document outline. Choose it by structure (one h1 per page, no skipped levels) and use size for the look."
+    - "size defaults to the level, so a bare <Heading as=\"h3\"> renders at h3 size; only pass size when the look must differ from the level."
+  radixHandles: false
+pitfalls:
+  - "as defaults to h2, not h1. Pages that need an h1 must say so."
+  - "size uses the t-* names (h1-h6, display-sm to display-2xl), not Text's numeric 1-9 scale."
+canonicalSnippet: |
+  import { Heading } from "@adres/mgda-ui"
+
+  <Heading as="h1" size="h3">
+    Welcome back
+  </Heading>
+reviewedAt: 2026-10-05
+reviewedAgainstContractHash: "00b98cc74dc9"
+---
+
+## Usage
+
+`Heading` fills the gap `Text` leaves: `Text` renders inline and block text
+tags but never `h1`-`h6`. Use `as` for the outline level and `size` for the
+look. Sizes map straight onto the `t-*` heading and display utilities in
+`typography.css`, so brand typography overrides apply.
+
+When `size` is omitted it follows the level, which covers most headings. Pass
+`size` only when structure and design disagree, such as a sign-in screen whose
+single `h1` should read at `h3` size.

package/knowledge/hero.md

@@ -0,0 +1,361 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: hero
+  sourceFile: packages/design-system/src/components/hero.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Hero
+      kind: component
+      typeText: "ForwardRefExoticComponent<HeroProps & RefAttributes<HTMLDivElement>>"
+    - name: HeroLayout
+      kind: type
+    - name: HeroProps
+      kind: type
+    - name: HeroStat
+      kind: type
+  primaryExport: Hero
+  subcomponents: []
+  props:
+    Hero:
+      - name: actions
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "CTA action slots - typically primary + secondary buttons."
+      - name: badge
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Pill / live-indicator badge. split: above headline. cinematic: top-right."
+      - name: badges
+        type: "string[]"
+        required: false
+        declaredIn: self
+        doc: "Trust-point strings shown below the search widget. A checkmark is prepended to each."
+      - name: borderless
+        type: boolean
+        required: false
+        declaredIn: card
+        doc: "When true, removes the border and shadow from the card."
+      - name: brand
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Brand identity element - cinematic top-left logo."
+      - name: brands
+        type: "ReactNode[]"
+        required: false
+        declaredIn: self
+        doc: "Brand name list for the magazine footer strip."
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional supporting paragraph."
+      - name: elevation
+        type: CardElevation
+        required: false
+        declaredIn: card
+        doc: "Surface elevation - bundles a background fill with a shadow into one level, overriding the variant's own background and shadow (the variant's border, if any, is kept). Reads the brand-themeable --elevation-* tokens. level0 - transparent, flat level1 - translucent surface (50%), flat level2 - solid surface + subtle shadow level3 - solid surface + stronger shadow Left unset, the card keeps its variant's default (brand-themeable) chrome."
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional pre-headline label / eyebrow. In magazine layout, appears in the footer-left strip."
+      - name: gap
+        type: CardGap
+        required: false
+        declaredIn: card
+        doc: "When set, makes the card a vertical flex column with the given gap between children. sm=12px md=16px lg=20px xl=24px"
+      - name: headline
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "Required: the marketing headline. Accepts JSX for styled spans."
+      - name: hoverEffect
+        type: "\"lift\" | \"scale\""
+        required: false
+        declaredIn: card
+        doc: "Hover animation style when `interactive` is true. \"scale\" (default) - a light zoom (1.03×) that raises the shadow one level · \"lift\" - translates up 4px"
+      - name: interactive
+        type: boolean
+        required: false
+        declaredIn: card
+        doc: "When true, the card zooms subtly on hover. Disabled by reduced-motion preference."
+      - name: layout
+        type: HeroLayout
+        required: false
+        declaredIn: self
+        doc: "Visual template. Defaults to \"split\" when media is set, \"centered\" otherwise."
+      - name: media
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Main image / media slot."
+      - name: overlay
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Content overlaid on the media column - split floating cards, badges, etc."
+      - name: padding
+        type: CardPadding
+        required: false
+        declaredIn: card
+        doc: "Padding inside the card. All responsive variants scale from their mobile floor up to the named size at XL (1280px+), one step per breakpoint. Fixed: none · sm(12px) · md(16px) Responsive: lg(→20px) · xl(→24px) · 2xl(→32px) · 3xl(→40px) · 4xl(→48px)"
+      - name: search
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Search widget slot - rendered below description in the \"search\" layout."
+      - name: secondaryMedia
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Secondary image slot - magazine right column."
+      - name: sectioned
+        type: boolean
+        required: false
+        declaredIn: card
+        doc: "Split the card into a muted header band with a content section beneath it. The card's own padding is dropped and each sub-component (CardHeader / CardContent / CardFooter) supplies its own padding instead; the header runs full-bleed with `bg-muted` + a bottom divider, its top corners rounded by the card's own radius."
+      - name: stats
+        type: "HeroStat[]"
+        required: false
+        declaredIn: self
+        doc: "Metric pairs rendered below content (capsule/split) or in a bottom grid (cinematic)."
+      - name: theme
+        type: "\"dark\" | \"light\""
+        required: false
+        declaredIn: self
+        doc: "\"dark\" applies a deep neutral background - intended for the cinematic layout."
+      - name: variant
+        type: CardVariant
+        required: false
+        declaredIn: card
+        doc: "Visual treatment of the card surface."
+  extendsProps:
+    - CardProps
+  variants:
+    layout:
+      kind: enum
+      options:
+        - search
+        - split
+        - centered
+        - capsule
+        - magazine
+        - cinematic
+        - editorial
+        - mosaic
+      default: null
+      on: Hero
+    theme:
+      kind: enum
+      options:
+        - light
+        - dark
+      default: null
+      on: Hero
+    variant:
+      kind: enum
+      options:
+        - default
+        - ghost
+        - surface
+      default: null
+      on: Hero
+    padding:
+      kind: enum
+      options:
+        - none
+        - sm
+        - md
+        - lg
+        - xl
+        - "2xl"
+        - "3xl"
+        - "4xl"
+      default: none
+      on: Hero
+    gap:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - xl
+      default: null
+      on: Hero
+    elevation:
+      kind: enum
+      options:
+        - none
+        - sm
+        - xs
+        - level0
+        - level1
+        - level2
+        - level3
+      default: null
+      on: Hero
+    hoverEffect:
+      kind: enum
+      options:
+        - lift
+        - scale
+      default: null
+      on: Hero
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - card
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - lucide-react
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-hero--default
+    - exportName: Split
+      id: components-hero--split
+  storybookTitle: Components/Hero
+  docsId: components-hero--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "97741dc45938"
+  factsHash: "4c36572d7592"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The top-of-page marketing block, in eight layout templates over one prop set."
+useWhen:
+  - "opening a marketing or landing page with a headline and a call to action"
+  - "you want a named editorial layout rather than assembling one from primitives"
+  - "the page opens with a search box as its main action (search layout)"
+useInstead:
+  - id: page-header
+    when: "this is an app screen, not marketing: a title row above content"
+  - id: cta
+    when: "it is a closing call to action rather than the page opening"
+  - id: feature-grid
+    when: "you are listing capabilities rather than leading with one headline"
+related:
+  - page-header
+  - cta
+  - feature-grid
+  - card
+  - stats
+composesWith:
+  - button
+  - badge
+  - search
+tokens:
+  - "--foreground"
+  - "--muted-foreground"
+  - "--primary"
+  - "--accent"
+  - "--border"
+  - "--muted"
+  - "--background"
+  - "--neutral-950"
+  - "--neutral-900"
+  - "--neutral-800"
+  - "--neutral-500"
+  - "--neutral-400"
+  - "--neutral-50"
+a11y:
+  notes:
+    - "Every layout renders the headline as an h1, so a page must contain at most one Hero or the heading outline breaks."
+    - "Entry animation is skipped entirely when prefers-reduced-motion is set, via useReducedMotion rather than a CSS-only guard."
+    - "headline accepts JSX for styled spans. Keep the emphasis visual: do not build the sentence out of nested elements that read oddly when linearised."
+    - "The cinematic glow layers are decorative and pointer-events-none, so they never intercept clicks or reach the accessibility tree."
+    - "theme: dark applies its own dark surface independently of the app's dark class, so verify contrast for actions placed on it rather than assuming brand tokens adapt."
+  requiredProps:
+    - "headline"
+  keyboard:
+    - "No interactive behaviour of its own. Anything focusable arrives through the actions, search or overlay slots and keeps its own semantics."
+  radixHandles: false
+pitfalls:
+  - "layout has no static default. It resolves to split when media is set and centered when it is not, so adding a media prop silently changes the entire template."
+  - "Each layout consumes a different subset of props and ignores the rest without warning. search and badges only render in the search layout; secondaryMedia and brands only in magazine; brand and the dark treatment only in cinematic; overlay only in split. Passing them elsewhere does nothing at all."
+  - "stats means something different per layout. capsule features stats[0] and rows the remainder; magazine uses only stats[0] and stats[1] and silently drops the rest; cinematic renders all of them in a grid whose column count equals stats.length, so a long list gets very narrow columns."
+  - "capsule and magazine hide description below the md breakpoint (hidden md:block). Copy that only exists in description is invisible on mobile."
+  - "Hero extends CardProps but overrides padding to none, because each layout owns its own interior spacing. Passing a padding value fights the layout."
+  - "The cinematic layout forces the Card variant to ghost so its own background is not covered by bg-card. Passing variant explicitly overrides that and can reintroduce the conflict."
+  - "theme: dark writes an inline background from --neutral-950 and switches the cinematic text colours to inline neutral values. It is one of the few places in the system that sets colour outside a semantic token, so it does not follow a brand's dark palette."
+rtl: "Mostly safe: layouts are flex and grid with logical spacing. The cinematic decorative glows are positioned with physical left and right offsets and will not mirror, though being blurred background shapes this reads as acceptable."
+brandNotes: "Everything outside cinematic traces to semantic tokens and re-skins cleanly. cinematic plus theme: dark is the exception: it hardcodes the neutral ramp, so a brand with a distinctive dark surface will not see it applied there."
+canonicalSnippet: |
+  import { Hero, Button } from "@adres/mgda-ui"
+
+  <Hero
+    layout="split"
+    eyebrow="New release"
+    headline="Find your next home"
+    description="Search verified listings across the city."
+    media={<img src="/hero.jpg" alt="" />}
+    stats={[{ value: "12k", label: "Listings" }]}
+    actions={
+      <>
+        <Button variant="primary">Start searching</Button>
+        <Button variant="outline">Book a viewing</Button>
+      </>
+    }
+  />
+reviewedAt: 2026-08-24
+reviewedAgainstContractHash: 97741dc45938
+---
+
+## Usage
+
+Hero is eight editorial templates sharing one prop set. Pick the template first, then
+fill only the props that template actually reads, because anything else is ignored in
+silence.
+
+It builds on `Card` (so `variant`, `elevation` and the rest come through) but forces
+`padding` to `none`: every layout owns its interior spacing, and overriding padding
+fights it.
+
+The headline is the only required prop, and it renders as an `h1` in all eight
+layouts, so a page gets one Hero.
+
+### Layouts, and what each one actually uses
+
+`layout` has no fixed default: it resolves to `split` when `media` is present and
+`centered` when it is not.
+
+| Layout | Reads | Notably ignores |
+| --- | --- | --- |
+| `centered` | eyebrow, headline, description, actions | media, stats, badge |
+| `split` | badge, headline, description, actions, stats, media, overlay | eyebrow |
+| `capsule` | headline, description, media, stats, actions | eyebrow, badge |
+| `magazine` | headline, description, media, secondaryMedia, stats[0..1], eyebrow, brands | actions, badge |
+| `editorial` | eyebrow, badge, headline, description, stats, actions | media |
+| `mosaic` | eyebrow, headline, description, actions, media | stats, badge |
+| `search` | eyebrow, headline, description, search, badges | media, stats, actions |
+| `cinematic` | brand, badge, eyebrow, headline, description, actions, stats, theme | media, overlay |
+
+Two consequences worth internalising. `magazine` reads only the first two `stats` and
+drops the rest without complaint. `capsule` and `magazine` hide `description` below the
+`md` breakpoint, so anything essential must not live only there.
+
+### The dark treatment
+
+`theme="dark"` is not the app's dark mode. It paints an inline background from the
+neutral ramp and switches the cinematic text colours to inline neutral values, which
+is the one place this component steps outside semantic tokens. Use it with
+`cinematic`, which it was designed for, and check the contrast of any actions you put
+on it.