@ai.all/ds7 0.0.0-stage → 2.0.0

package/01-architecture/ATOMIC-DESIGN.md

@@ -0,0 +1,68 @@
+# 01 · Atomic Design and component levels
+
+Components are organised in five levels, after [Brad Frost's Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/). Each level depends only on the levels below it. The goal is that a block works anywhere: on a page, in a sidebar, in a modal, or nested inside another block.
+
+---
+
+## 1. Levels
+
+```
+[1. Atoms]       indivisible parts: button, icon, badge, field, price
+      │
+[2. Molecules]   small groups of atoms: product card, plan card, slider controls
+      │
+[3. Organisms]   self-contained widgets: card slider, feature grid, FAQ, calculator
+      │
+[4. Templates]   section layouts that compose organisms
+      │
+[5. Pages]       routes: fetch data, set SEO, pass props
+```
+
+---
+
+## 2. Rules per level
+
+### Atoms — `app/components/ui/`
+- Examples: `UiButton`, `UiIcon`, `UiPrice`, `UiBadge`, `UiField`, `UiLink`.
+- Know nothing about pages, products or application state.
+- Styled with a base class and short modifiers: `.btn.-sun`, `.btn.-sm`, `.btn.-outline`.
+
+### Molecules — `app/components/ui/`
+- Examples: `UiProductCard`, `UiSectionHeading`, `UiFeatureCard`, `UiPlanCard`, `UiSliderNav`.
+- Built only from atoms and plain markup. Typed props and slots. No side effects.
+- Must look right in a four-column grid and in a narrow sidebar. Use container queries.
+
+### Organisms — `app/components/ui/`, `sections/`, `site/`
+- Examples: `UiCardSlider`, `UiFeatureGrid`, `UiFaq`, `CalcPanel`, `SiteHeader`, `SiteFooter`.
+- Own their local state: scroll position, active tab, open accordion item.
+- Work through slots. A slider does not know that it shows products; it shows whatever molecules it receives.
+
+### Templates and sections — `app/components/sections/`
+- Compose organisms into a complete block of a page.
+- No URL-specific logic and no hard-coded page content.
+
+### Pages — `app/pages/`
+Pages do three things only:
+1. Call composables that read data from `app/data/`.
+2. Set page metadata (`usePageSeo`).
+3. Pass data to sections as props.
+
+Pages do not contain inline card markup, custom sliders or bespoke grids.
+
+---
+
+## 3. Embedding rule
+
+Every component must be placeable:
+1. in normal page flow;
+2. inside a modal;
+3. inside a tab or a calculator panel;
+4. inside a narrow sidebar or a drawer.
+
+Size comes from the parent box (`@container`), not from the screen (`@media`).
+
+---
+
+## 4. Brand first
+
+Levels are built top-down from the brandbook. Atoms come from tokens and the sandbox entries in `02-design-system/BRANDBOOK-SANDBOX.md`. A component that exists only in a page is not finished until it is in the sandbox.

package/01-architecture/COMPONENT-ANATOMY.md

@@ -0,0 +1,101 @@
+# 01 · Component anatomy and container queries
+
+The reference shape of a Vue 3 single-file component in DS7. The template file is in `templates/component.vue`.
+
+---
+
+## 1. Shape
+
+```vue
+<script setup lang="ts">
+/**
+ * UiProductCard — product card molecule.
+ * Container-aware. Modifiers are separate classes.
+ */
+
+const props = withDefaults(defineProps<{
+  title: string
+  description?: string
+  price?: number | null
+  badge?: 'top' | 'new' | 'sale'
+  specs?: Array<{ label: string; value: string }>
+  top?: boolean
+  compact?: boolean
+  dark?: boolean
+}>(), {
+  description: '',
+  price: null,
+  specs: () => [],
+  top: false,
+  compact: false,
+  dark: false,
+})
+
+const rootClasses = computed(() => [
+  'p-card',
+  props.top && '-top',
+  props.compact && '-compact',
+  props.dark && '-dark',
+  props.badge && `-${props.badge}`,
+])
+</script>
+
+<template>
+  <article :class="rootClasses" data-ref="CARD-01">
+    <div class="p-card__art">
+      <slot name="art" />
+    </div>
+
+    <div class="p-card__body">
+      <h3 class="p-card__title">{{ title }}</h3>
+      <p v-if="description" class="p-card__desc">{{ description }}</p>
+      <dl v-if="specs.length" class="p-card__specs">
+        <div v-for="s in specs" :key="s.label">
+          <dt>{{ s.label }}</dt>
+          <dd>{{ s.value }}</dd>
+        </div>
+      </dl>
+    </div>
+
+    <div class="p-card__footer">
+      <UiPrice v-if="price !== null" :amount="price" />
+      <slot name="action" />
+    </div>
+  </article>
+</template>
+
+<style>
+.p-card {
+  --card-bg: var(--color-white);
+  --card-ink: var(--color-ink);
+
+  container-type: inline-size;
+  display: flex;
+  flex-direction: column;
+  background: var(--card-bg);
+  color: var(--card-ink);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+}
+
+@container (max-width: 320px) {
+  .p-card {
+    padding: var(--space-2);
+  }
+  .p-card__title {
+    font-size: 0.9rem;
+  }
+}
+</style>
+```
+
+---
+
+## 2. Rules
+
+1. **Typed props.** Booleans for modifiers keep templates readable; `rootClasses` turns them into classes.
+2. **`container-type: inline-size`** on any component with responsive states. It reacts to its box, not to the screen.
+3. **Component-level custom properties** (`--card-bg`, `--card-ink`). Modifiers change the variables, not ten child selectors.
+4. **Stable ID** in `data-ref` (`CARD-01`). It links the live component to its entry in the brandbook.
+5. **Slots with fallbacks** for media and actions. The component works with any content in those slots.
+6. **A one-line summary** at the top of the file, as in the example.

package/01-architecture/MODIFIER-SYSTEM.md

@@ -0,0 +1,90 @@
+# 01 · Modifier system and ancestry scoping
+
+One base component, many variants, no duplicate components.
+
+---
+
+## 1. Syntax
+
+Use a base class plus separate modifier classes. Each modifier starts with a dash:
+
+```html
+<article class="p-card -top -new -compact">
+  <div class="p-card__art">…</div>
+  <h3 class="p-card__title">Panel 450 W</h3>
+  <div class="p-card__price">…</div>
+</article>
+```
+
+Why:
+- **Short class names** keep HTML and CSS small.
+- **Modifiers combine** freely: `-top -compact`, `-dark -lg`.
+- **Modifiers cascade:** a modifier on the root can change every child.
+
+Avoid long compound names such as `catalog-product-card--featured-large-dark`.
+
+---
+
+## 2. Cascade from a modifier
+
+```css
+.p-card {
+  --card-bg: var(--color-white);
+  --card-text: var(--color-ink);
+  --card-border: var(--color-ink-100);
+
+  background: var(--card-bg);
+  color: var(--card-text);
+  border: 1px solid var(--card-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+}
+
+.p-card.-top {
+  --card-border: var(--color-sun);
+  box-shadow: var(--shadow-lift);
+}
+.p-card.-top .p-card__title {
+  font-weight: 700;
+}
+
+.p-card.-compact {
+  padding: var(--space-2);
+}
+
+.p-card.-dark {
+  --card-bg: var(--color-ink-950);
+  --card-text: var(--color-white);
+  --card-border: rgba(255, 255, 255, 0.12);
+}
+```
+
+Modifiers change custom properties where possible. That keeps the number of selectors small.
+
+---
+
+## 3. Context from an ancestor
+
+Sometimes a shared component must look different on one page. Do not create a second component. Scope the difference by an ancestor:
+
+```css
+/* the hook everywhere */
+.hero-hook {
+  background: var(--color-paper);
+  color: var(--color-ink);
+}
+
+/* the same hook on a dark page */
+body.page-business .hero-hook {
+  background: var(--color-ink-950);
+  color: var(--color-white);
+}
+
+/* the same hook inside a modal */
+.site-modal-box .hero-hook {
+  background: transparent;
+  padding: 0;
+}
+```
+
+The page class on `<body>` is set by `usePageSeo` (`page-home`, `page-residential`, `page-business`, …). Wrong: `HookHome.vue` and `HookBusiness.vue`. Right: one `UiHeroHook` with context rules.

package/02-design-system/BRANDBOOK-SANDBOX.md

@@ -0,0 +1,52 @@
+# 02 · Brandbook and sandbox (`/ui`)
+
+The `/ui` page of a project is a live sandbox: every foundation token and every base component, shown in its real code. It is the shared vocabulary between people and agents.
+
+---
+
+## 1. Stable component IDs
+
+Every reusable pattern has one short ID:
+
+| ID | Name | Use |
+|---|---|---|
+| `BTN-01` | Primary button | main action; sun fill with an arrow |
+| `BTN-02` | Outline button | secondary action |
+| `CTL-01` | Segmented switch | tabs or periods |
+| `COUNTER-01` | Bounded numeric counter | number input with − / + buttons; variant `-inner` |
+| `PRICE-01` | Formatted price | amount with currency suffix and optional "from" label |
+| `CARD-01` | Base product card | catalogue item with modifiers |
+| `CARD-02` | Plan / tariff card | package with a list of options |
+| `SLD-01` | Card slider | scroll-snap slider with navigation |
+| `HOOK-01` | Overlap hook | panel that overlaps a cover image |
+
+**How it is used.** Instead of describing a card in full, say:
+
+> "Put `CARD-01 -top` in this block, with `BTN-01` as the action."
+
+Both a person and an agent understand that without a second description.
+
+---
+
+## 2. What the sandbox shows
+
+1. **Modifier toggles** for each component: `-top`, `-new`, `-compact`, `-dark`.
+2. **Background switch:** light, dark, inside a modal. Contrast is visible on each.
+3. **Copy code** next to each example: the reference snippet for pasting into a project.
+
+---
+
+## 3. Update rule
+
+Every new atom, molecule or token must appear in the sandbox before it is used on a page. A component that is missing from `/ui` is not finished. The sandbox is excluded from search indexing (`noindex, nofollow`) and from `sitemap.xml`.
+
+---
+
+## 4. Brand-first workflow
+
+1. Add or change foundations in `theme.css`.
+2. Add or change the entry in the sandbox.
+3. Build or change the component.
+4. Use the component on a page.
+
+Changing a token changes the sandbox first; the sandbox is the visual reference for review.

package/02-design-system/NAMING-CONVENTIONS.md

@@ -0,0 +1,45 @@
+# 02 · Naming conventions
+
+Short, semantic class names keep HTML small and make CSS readable. The formula and the rules are the same for every project.
+
+---
+
+## 1. Examples
+
+| Long name | DS7 name |
+|---|---|
+| `.catalog-product-card` | `.p-card` |
+| `.catalog-product-card--featured` | `.p-card.-top` |
+| `.catalog-product-card__description` | `.p-card__desc` |
+| `.section-heading-eyebrow` | `.s-head__eye` |
+| `.overlap-panel` | `.panel.-overlap` |
+| `.hook-bill-calculator` | `.hook.-bill` |
+| `.button-variant-primary-large` | `.btn.-sun.-lg` |
+
+---
+
+## 2. Formula
+
+```
+.[component]          base name, short kebab-case
+.[component]__[part]  element, double underscore
+.-[modifier]          modifier, separate class with a leading dash
+.is-[state]           state
+```
+
+---
+
+## 3. Rules
+
+1. **No word appended to a base name.** `.btn-lg`, `.card-big`, `.hero-active` are wrong. Write `.btn.-lg`, `.card.-big`, `.hero.is-active`.
+2. **Size and colour words are modifiers.** `-sm`, `-lg`, `-sun`, `-dark`. Not `-big`, `-red`, `-orange`.
+3. **Element names describe the part.** `__title`, `__price`, `__art`, not `__text2` or `__left`.
+4. **Only tokens in values.** Naming does not replace the token rule in `TOKENS-SPEC.md`.
+
+---
+
+## 4. Build-time minification
+
+- Unused styles are removed when the site is generated. Only classes that appear in the output ship.
+- The CSS minifier removes comments and shortens values (`#ffffff` → `#fff`).
+- Critical CSS is inlined; the rest is a cached file with a content hash in its name.

package/02-design-system/TOKENS-SPEC.md

@@ -0,0 +1,102 @@
+# 02 · Design tokens
+
+Tokens are the foundations: the named values every component uses. They live as CSS custom properties in `app/assets/css/theme.css`. Components read tokens only; they never contain raw values.
+
+Format for tools that need it: the [W3C Design Tokens Format Module (2025.10)](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/), with `$value` and `$type`.
+
+---
+
+## 1. Colour
+
+```css
+:root {
+  /* surfaces and text */
+  --color-paper: #f7f5ef;             /* page background */
+  --color-white: #ffffff;             /* cards, panels */
+  --color-ink: #1f1b16;               /* main text */
+  --color-ink-500: #6b6459;           /* secondary text */
+  --color-ink-100: rgba(31, 27, 22, 0.08); /* borders, dividers */
+  --color-ink-950: #12100d;           /* dark inversions */
+
+  /* brand accent */
+  --color-sun: #ffd84d;
+  --color-sun-hover: #ffcf2e;
+
+  /* semantic */
+  --color-success: #2e7d32;
+  --color-warning: #ed6c02;
+  --color-error: #d32f2f;
+}
+```
+
+**Contrast rule.** `--color-sun` is never used for text. It is a fill (buttons), a badge background, or a marker (`box-shadow: inset 0 -0.3em 0 var(--color-sun)`).
+
+**Measure, do not estimate.** When a palette changes, check the contrast of every text and border pair with a tool, and record the result in the brandbook.
+
+---
+
+## 2. Spacing
+
+```css
+:root {
+  --space-1: 0.25rem;   /* 4 px */
+  --space-2: 0.5rem;    /* 8 px */
+  --space-3: 0.75rem;   /* 12 px */
+  --space-4: 1rem;      /* 16 px */
+  --space-6: 1.5rem;    /* 24 px */
+  --space-8: 2rem;      /* 32 px */
+  --space-12: 3rem;     /* 48 px */
+  --space-16: 4rem;     /* 64 px */
+
+  /* responsive section rhythm */
+  --space-single: clamp(1.2rem, 3vw, 2.2rem);
+  --space-double: clamp(2.4rem, 6vw, 4.5rem);
+  --space-triple: clamp(3.6rem, 9vw, 6.5rem);
+
+  /* page grid */
+  --content-width: 78rem;               /* 1248 px */
+  --page-gutter: clamp(1rem, 3.5vw, 2rem);
+}
+```
+
+---
+
+## 3. Elevation
+
+```css
+:root {
+  --shadow-lift: 0 4px 16px -2px rgba(31, 27, 22, 0.06);   /* resting cards */
+  --shadow-hover: 0 12px 32px -4px rgba(31, 27, 22, 0.12); /* hover, open items */
+  --shadow-modal: 0 24px 64px -8px rgba(18, 16, 13, 0.24); /* modal dialogs */
+}
+```
+
+Use these three. Do not write ad-hoc `box-shadow` values in components.
+
+---
+
+## 4. Radius
+
+```css
+:root {
+  --radius-sm: 0.375rem;  /* 6 px — badges, chips */
+  --radius-md: 0.75rem;   /* 12 px — cards, inputs */
+  --radius-lg: 1.25rem;   /* 20 px — large section panels */
+  --radius-full: 9999px;  /* pills, round buttons */
+}
+```
+
+---
+
+## 5. Breakpoints
+
+```css
+:root {
+  --bp-sm: 480px;   /* one column below this */
+  --bp-md: 800px;   /* tablet-portrait boundary */
+  --bp-lg: 900px;   /* two-column grids collapse here */
+  --bp-xl: 1200px;  /* desktop layout */
+}
+```
+
+Media queries use these values. Components prefer container queries.

package/03-performance-web-vitals/ASSETS-PIPELINE.md

@@ -0,0 +1,62 @@
+# 03 · Assets pipeline: tight trim and responsive images
+
+Images are prepared before they reach the code. Raw exports make pages heavy and products small.
+
+---
+
+## 1. Tight trim
+
+Typical problem: a product PNG exported on a 1000 × 1000 canvas where most pixels are empty transparent margin.
+
+Costs: extra bytes, off-centre objects in grids, and tiny products on phones.
+
+Rules:
+1. **Crop to the object** along its outline, keeping a real soft shadow if the design has one.
+2. **Keep transparency** for product cut-outs so they sit on light, dark and coloured backgrounds.
+3. **Fix the box.** The container has a stable `aspect-ratio` (`4/3` or `1/1`); the image is centred with `object-fit: contain`.
+
+---
+
+## 2. Responsive images
+
+Every raster image ships in several sizes. The reference component is `UiImg`: it takes a `src` string, builds a `srcset` from the generated variants, and writes `width`, `height` and lazy-loading attributes.
+
+Generated sizes (default): **400, 800 and 1200 px wide**, WebP, quality 82. Images smaller than 900 px are not resized up.
+
+```html
+<img
+  src="/images/p/hero-1200.webp"
+  srcset="/images/p/hero-400.webp 400w, /images/p/hero-800.webp 800w, /images/p/hero-1200.webp 1200w"
+  sizes="(max-width: 800px) 100vw, 60vw"
+  width="1200" height="900"
+  alt="Solar installation on a rooftop"
+  fetchpriority="high" loading="eager" decoding="async"
+>
+```
+
+Use `UiImg` rather than writing this by hand in every page.
+
+---
+
+## 3. Loading priorities
+
+| Position | `loading` | `fetchpriority` | `decoding` |
+|---|---|---|---|
+| The LCP image above the fold | `eager` | `high` | `async` |
+| Cards below the fold | `lazy` | `auto` | `async` |
+| Footer and late sections | `lazy` | `low` | `async` |
+
+Only one image is the LCP image on a page. Mark it, do not mark several.
+
+---
+
+## 4. Asset script
+
+Keep a small script in `tools/` (Sharp or Python) that:
+- takes new images from a source folder;
+- trims transparent margins;
+- writes WebP (and AVIF where useful) at 400, 800 and 1200 px;
+- writes `app/data/image-variants.json`, the manifest `UiImg` reads;
+- has a `--check` mode that fails when a referenced image has no manifest entry.
+
+Commit the manifest with the images it describes.

package/03-performance-web-vitals/CRITICAL-CSS.md

@@ -0,0 +1,39 @@
+# 03 · Critical CSS and render-blocking
+
+A stylesheet in `<head>` blocks rendering until it has downloaded and parsed. On a slow mobile network a 50–150 KB stylesheet delays the first paint noticeably.
+
+---
+
+## 1. Split
+
+- **Above the fold:** header, page grid, typography and the first screen. Needed for the first paint.
+- **Below the fold:** calculators, reviews, map, footer, modals. Needed later.
+
+---
+
+## 2. Nuxt configuration
+
+```ts
+export default defineNuxtConfig({
+  experimental: {
+    inlineSSRStyles: true,   // inline the CSS each page uses during generation
+  },
+})
+```
+
+During `nuxt generate`:
+- each page is rendered and the classes it uses are collected;
+- those rules are inlined in `<style>` in the page `<head>`;
+- the full stylesheet is loaded afterwards with `rel="preload"`.
+
+---
+
+## 3. What to measure
+
+Record First Contentful Paint and render-blocking requests on a real phone, with the build and date, in `docs/METRICS.md`. Lab numbers from a sandbox are not evidence for this.
+
+---
+
+## 4. Budget
+
+Keep the entry stylesheet small enough to inline without delaying HTML. Set a budget in `docs/METRICS.md` and check it when the stylesheet changes.

package/03-performance-web-vitals/FONTS-ZERO-CLS.md

@@ -0,0 +1,59 @@
+# 03 · Fonts and zero layout shift
+
+Text that jumps when a web font arrives moves the whole page and raises CLS. This document describes how DS7 avoids that.
+
+---
+
+## 1. The problem
+
+1. The browser draws text with a system font first (Arial or Helvetica).
+2. The system font has different glyph widths and line heights from the brand font.
+3. When the brand font arrives, lines re-wrap and content moves, often 20–40 px.
+
+---
+
+## 2. The approach
+
+### Step 1: preload one weight
+Preload the weight used on the first screen, as `woff2`, from the document `<head>`:
+
+```ts
+// nuxt.config.ts → app.head.link
+{
+  rel: 'preload',
+  href: '/fonts/brand-latin-var.woff2',
+  as: 'font',
+  type: 'font/woff2',
+  crossorigin: 'anonymous',
+}
+```
+
+### Step 2: matched fallback
+A fallback `@font-face` built from a system font, with metrics adjusted to the brand font:
+
+```css
+@font-face {
+  font-family: 'Brand Fallback';
+  src: local('Arial');
+  ascent-override: 95.8%;
+  descent-override: 28.2%;
+  line-gap-override: 0%;
+  size-adjust: 101.4%;
+}
+```
+
+The values come from the brand font's metrics (the `@nuxtjs/fontaine` module computes them). When the brand font loads, glyphs have the same advance widths and line boxes, so text does not move.
+
+### Step 3: `font-display: swap`
+Text appears at once with the fallback and swaps when the brand font is ready. No invisible text.
+
+---
+
+## 3. Checklist
+
+- [ ] One preloaded weight for the first screen.
+- [ ] Fallback with `size-adjust` and the override metrics.
+- [ ] Every logo and inline SVG has `width` and `height`.
+- [ ] Every card and media box has a fixed `aspect-ratio`.
+- [ ] Fixed-position panels (cookie banner, intro) do not push content.
+- [ ] Measured CLS recorded in `docs/METRICS.md` on a real device.

package/03-performance-web-vitals/HYDRATION-STRATEGY.md

@@ -0,0 +1,68 @@
+# 03 · Hydration strategy
+
+Static HTML appears first. Then the framework attaches event handlers to each component (hydration). On a phone with many interactive components this can block the main thread for hundreds of milliseconds, and taps are ignored during that time.
+
+---
+
+## 1. Principle
+
+Hydrate only what the visitor needs now.
+
+- **Critical:** navigation, the first interactive element, forms the visitor sees.
+- **Idle:** chat widgets, cookie banner, sound controls, modals that are not open.
+- **On visibility:** heavy sections below the fold (maps, charts, interactive calculators).
+
+---
+
+## 2. Idle widgets
+
+```vue
+<script setup lang="ts">
+const ready = ref(false)
+
+onMounted(() => {
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(() => { ready.value = true })
+  } else {
+    setTimeout(() => { ready.value = true }, 1500)
+  }
+})
+</script>
+
+<template>
+  <ClientOnly>
+    <SiteChat v-if="ready" />
+    <SiteCookieBanner v-if="ready" />
+  </ClientOnly>
+}
+</template>
+```
+
+Note for the banner: it must not hide content while it waits. Reserve its space with a fixed position.
+
+---
+
+## 3. Visibility
+
+Heavy sections use lazy components that hydrate when they approach the viewport:
+
+```vue
+<LazyHomeProjectMap hydrate-on-visible />
+```
+
+---
+
+## 4. Passive listeners
+
+Scroll and touch listeners that never call `preventDefault` are registered as passive, so the browser can scroll without waiting for the script:
+
+```ts
+window.addEventListener('scroll', onScroll, { passive: true })
+track.addEventListener('touchstart', onTouchStart, { passive: true })
+```
+
+---
+
+## 5. Measuring
+
+Total Blocking Time and Interaction to Next Paint are measured on a real device, not in a sandbox. Record the results in `docs/METRICS.md`.