# Kupp-west Apple Clean – conventions for building with this system

This system is the "Apple Clean" design of the Kupp-west eBay listing template
(`variants/23-apple-clean`). Everything visual comes from one stylesheet of
semantic `kwac-*` classes; the React components in this bundle only emit that
markup, so a design built here can be copied 1:1 into the static HTML template.

## 1. Wrap everything in `Page`

`Page` renders `<div class="kwac">`, and that element carries the color tokens,
the Helvetica stack, the 17px/1.6 body type and the near-white background.
Without it every component renders unstyled. Nothing else is required: no
theme provider, no font loading (system fonts only), no icon library.

```jsx
<Page>
  <Summary>…</Summary>
  <Header />
  <VehicleBar model="VW Touran Typ: 5T1" facts="Komplettsatz · Baujahr 05.2015 – jetzt" />
  <Hero eyebrow="Komplettset für den VW Touran 5T1" title="Die Anhängerkupplung für Ihren Touran. Komplett gedacht." lead="…" links={[{ label: 'Technische Daten', href: '#kwac-daten' }]} />
  <StatsRow><Stat value="1.800" unit="kg Anhängelast" /><Stat value="75" unit="kg Stützlast" /></StatsRow>
  <Section alt id="kwac-fahrzeuge" statement="Passt es? Hier steht es." copy="…">
    <VehicleTable columns={['HSN / TSN', 'Marke & Fahrzeugtyp', 'Baujahr', 'PS / KW']} rows={[…]} />
  </Section>
  <Section final statement="Bereit anzukuppeln?">
    <CtaActions><Button href="#kwac-fahrzeuge">Kompatibilität prüfen</Button></CtaActions>
  </Section>
  <Footer token="[kwkw-131282-153195-kwkw]">Anhängerkupplungen und fahrzeugspezifische Elektrosätze.</Footer>
</Page>
```

## 2. Styling idiom: semantic classes only, no utilities, no inline styles

- The page is a vertical stack of `Section` bands (`.kwac-band`, alternate
  `alt` on and off), each with a centered statement headline and optional copy,
  followed by ONE grid or table component. Do not nest sections.
- Every visual comes from a `kwac-*` class in `_ds_bundle.css`. Do not write
  Tailwind-style utility classes, do not invent new class names, do not use
  `style={{…}}` on listing markup – the real eBay template forbids inline
  styles, JavaScript, forms, iframes and any http:// resource.
- The body face is Inter (Google Fonts `@import` inside `_ds_bundle.css`),
  falling back to Helvetica/Arial.
- Colors are the eight custom properties on `.kwac` (also mirrored on `:root`
  in `tokens/colors.css`): `--bg`, `--bg-alt`, `--ink`, `--muted`, `--hair`,
  `--blue`, `--blue-deep`, `--dark`. Blue is the only accent: links, buttons,
  chips, the highlighted offer outline. No other hue, no gradients, no shadows.
- The long product page (template "Produktseite") opens with `DarkHero` instead
  of `Hero` (near-black band with product tiles and the "Passend für" row) and
  adds `LoadComparison` (dark, left-aligned pill bars) after the feature band.
  These two are the only dark surfaces; use `--ink-on-dark`, `--muted-on-dark`,
  `--label-on-dark` and `--blue-on-dark` on them, never the light-mode tokens.
- Buttons are `<a>` pills: `Button` (primary filled, `variant="ghost"`
  outlined, `size="compact"` for the sticky bar). Links are `TextLink`
  (`.kwac-link` with chevron, `variant="inline"` inside copy).
- Grids come in container/item pairs and are fixed by CSS to the column counts
  of the template: `Gallery`/`GalleryItem` (3), `FeatureTrio`/`Feature` (3),
  `IncludedGrid`/`IncludedItem` (5), `Offers`/`OfferCard` (2),
  `DetailGrid`/`DetailCard` (2), `NoteGrid`/`NoteCard` (2), `SpecGrid`/
  `SpecColumn` (2), `FaqGrid`/`FaqItem` (2), `MoreOffers`/`MoreOfferCard` (4).
  All collapse responsively below 900px / 740px / 400px on their own.
- Class vocabulary you will see in the markup (all in `_ds_bundle.css`):
  `kwac-band`, `kwac-band-alt`, `kwac-final`, `kwac-statement`,
  `kwac-band-copy`, `kwac-hero`, `kwac-h1`, `kwac-lead`, `kwac-stats`,
  `kwac-stat`, `kwac-fit`, `kwac-gallery`, `kwac-trio`, `kwac-included`,
  `kwac-offers`, `kwac-offer`, `kwac-offer-this`, `kwac-offer-chip`,
  `kwac-button`, `kwac-button-ghost`, `kwac-cta`, `kwac-link`,
  `kwac-hero-dark`, `kwac-hero-tile`, `kwac-hero-fit`, `kwac-compare`,
  `kwac-bars`, `kwac-bar`, `kwac-tablewrap`, `kwac-table`, `kwac-specs`, `kwac-spec-table`,
  `kwac-detail`, `kwac-notes`, `kwac-doclist`, `kwac-more`, `kwac-brands`,
  `kwac-faq`, `kwac-footer`.
- If a layout truly does not exist here, compose it from `Section` plus an
  existing grid and say so; a new pattern means a new `kwac-*` class in the
  central stylesheet, never ad-hoc styling in the listing.

## 3. Content rules (German, engineer-to-buyer)

Formal *Sie*, short declaratives, no exclamation marks, no emoji, exact
unrounded numbers ("1.800 kg", "9,9 kN"), technical nouns used confidently
(Anhängelast, Stützlast, D-Wert, Datenbus, Check-Control, PDC-Abschaltung).
Statement headlines are two short sentences ("1.800 kg. Zieht, was Sie
vorhaben."). CTAs are verb + object ("Kompatibilität prüfen"). Unknown values
are shown as "—", never invented.

## 4. Where the truth lives

- `styles.css` imports `tokens/*.css` and `_ds_bundle.css`; the latter IS
  `variants/23-apple-clean/styles.css`, the one stylesheet of the template.
- `components/<group>/<Name>/<Name>.prompt.md` documents props and placement
  per component; `<Name>.d.ts` is the exact prop contract.

# KuppwestAppleClean (@kuppwest/apple-clean@0.1.0)

This design system is the published @kuppwest/apple-clean React library, bundled as a single
browser global. All 36 components are the real upstream code.

## Where things are

- `_ds_bundle.js` — the whole-DS bundle at the project root; loads every component to `window.KuppwestAppleClean`. First line is a `/* @ds-bundle: … */` metadata header.
- `styles.css` — the single stylesheet entry: it `@import`s the tokens, fonts, and component styles (`_ds_bundle.css`). Link this one file.
- `components/<group>/<Name>/<Name>.prompt.md` (example JSX + variants), `<Name>.d.ts` (types), `<Name>.html` (variant grid).
- `tokens/*.css` — CSS custom properties, names verbatim from upstream.
- `fonts/` — `@font-face` files + `fonts.css` (when the package ships fonts).

For a specific component, `read_file("components/<group>/<Name>/<Name>.prompt.md")`.

## Loading

Add these two lines to your page once (React must be on the page first):

```html
<link rel="stylesheet" href="styles.css">
<script src="_ds_bundle.js"></script>
```

Components are then available at `window.KuppwestAppleClean.*`. Mount into a dedicated child node (e.g. `<div id="ds-root">`), not the host page's own React root, so the two trees don't collide:

```jsx
const { BrandsStrip } = window.KuppwestAppleClean;
ReactDOM.createRoot(document.getElementById('ds-root')).render(<BrandsStrip />);
```

Wrap the tree in the provider — most components read theme/i18n from context:

```jsx
<Page>{children}</Page>
```

## Tokens

29 CSS custom properties from @kuppwest/apple-clean-tokens. Names are
preserved verbatim from upstream. See `tokens/` for the full list.

- **color** (8): `--bg-alt`, `--text-body`, `--text-statement`, …
- **spacing** (5): `--space-band`, `--space-band-final`, `--space-gutter`, …
- **typography** (1): `--font-sans`
- **radius** (5): `--radius-card`, `--radius-tile`, `--radius-inner`, …
- **other** (10): `--bg`, `--ink`, `--muted`, …

## Components

### marketing
- `BrandsStrip` — The one dark band of the page (.kwac-brands): near-black background, small

### core
- `Button` — Call-to-action pill. Renders an a with the semantic class kwac-button
- `Chip` — Small uppercase label chip (.kwac-offer-chip). Sits at the top of an
- `TextLink` — Blue text link in the Apple Clean idiom: no underline until hover, optional

### layout
- `CtaActions` — Centered horizontal row of call-to-action buttons (.kwac-final-actions),
- `Footer` — Page footer (.kwac-footer): hairline on top, centered wordmark, one muted
- `Header` — Centered page header (.kwac-header): the bold wordmark (.kwac-mark) over a
- `Page` — Root wrapper of every Apple Clean surface: renders div classkwac, which
- `Section` — Full-width content band (.kwac-band) with 96px vertical padding, centered
- `Summary` — Quiet one-line product summary at the very top of the listing

### product
- `DarkHero` — Dark full-bleed opening hero (.kwac-hero.kwac-hero-dark): near-black band
- `Gallery` — Three-column grid of white product tiles (.kwac-gallery), max 1080px wide.
- `GalleryItem` — White rounded tile (.kwac-gallery-item, 22px radius, 26px padding) with a
- `Hero` — Opening hero (.kwac-hero): centered eyebrow, oversized bold headline
- `Stat` — One key figure (.kwac-stat): an oversized thin number (.kwac-stat-num)
- `StatsRow` — Hairline-framed strip of key figures (.kwac-stats) under the hero: a

### cards
- `DetailCard` — Light-gray rounded card (.kwac-detail-card, white on alt bands) that
- `DetailGrid` — Two-column grid of component detail cards (.kwac-detail), max 960px,
- `FaqGrid` — Two-column grid of FAQ cards (.kwac-faq), max 960px, stacked below 740px.
- `FaqItem` — White rounded FAQ card (.kwac-faq-item, 18px radius) with the question as a
- `Feature` — One plain feature entry (.kwac-trio-item): bold title and a muted
- `FeatureTrio` — Three-column, left-aligned feature list (.kwac-trio) with wide 40px gaps
- `IncludedGrid` — Five-column grid of small white tiles (.kwac-included) listing what is in
- `IncludedItem` — Small white rounded tile (.kwac-included-item, 18px radius) with a bold
- `MoreOfferCard` — Linked product tile (.kwac-more-card): the image sits on a near-black
- `MoreOffers` — Four-column grid of linked product tiles (.kwac-more) pointing at related
- `NoteCard` — Light-gray rounded note card (.kwac-note) for good to know caveats and
- `NoteGrid` — Two-column grid of note cards (.kwac-notes), max 960px, stacked below 740px.
- `OfferCard` — White rounded offer card (.kwac-offer, 22px radius, 30px padding): Chip,
- `Offers` — Two-column comparison grid for offer cards (.kwac-offers). Always exactly

### data
- `FitNotice` — Left-aligned fit warning card (.kwac-fit): rounded 18px, hairline border,
- `LoadComparison` — Dark, left-aligned comparison band (.kwac-compare): eyebrow, statement,
- `SpecColumn` — White spec panel (.kwac-spec-col) with a heading and a two-column key/value
- `SpecGrid` — Two-column grid of spec panels (.kwac-specs), max 960px. Single column
- `VehicleTable` — Compatible-vehicles table (.kwac-tablewrap  .kwac-table): white rounded

### navigation
- `VehicleBar` — Sticky, translucent vehicle strip (.kwac-vbar) directly under the header: