@yottagraph-app/aether-instructions 1.1.24 → 1.1.26

package/commands/build_my_app.md

@@ -10,7 +10,7 @@ This command reads `DESIGN.md` (which contains the project creator's vision) and
 
 ---
 
-## Step 1: Read the Brief
+## Step 1: Read the Brief and Design References
 
 Read `DESIGN.md` from the project root.
 
@@ -26,6 +26,33 @@ Look for a `## Vision` section -- this contains the project creator's descriptio
 
 Stop here and wait for the user to describe what they want.
 
+### Long-form briefs
+
+If the Vision section is long (roughly 500+ words -- a full PRD, spec, or design doc), don't try to hold it all in your head at once. Instead:
+
+1. Read the full Vision section carefully.
+2. Extract the **core purpose** (one sentence: what is this app for?).
+3. Identify the **MVP feature set** -- the minimum set of features that delivers the core value. Look for explicit priority indicators (P0/P1, "must have" vs "nice to have", numbered phases). If none exist, use your judgment: what's the smallest thing that works end-to-end?
+4. Create `design/requirements.md` with your extracted requirements, grouped by priority. This becomes your working checklist.
+5. Build the MVP first, then iterate. Don't try to implement every detail from a long brief in one pass.
+
+### Design references
+
+Check for a `## Design References` section in DESIGN.md and for files in `design/references/`:
+
+```bash
+ls design/references/ 2>/dev/null
+```
+
+If design reference images exist (screenshots from Figma or other design tools):
+
+1. **Examine each image** -- these are design mockups from the project creator showing what the app should look like.
+2. Describe what you see in each image: layout structure, navigation patterns, component types, color usage, typography.
+3. Map visual elements to **Vuetify components** (cards = `v-card`, data tables = `v-data-table`, navigation drawers = `v-navigation-drawer`, app bars = `v-app-bar`, etc.). If a `vuetify-figma` skill is available in `.cursor/skills/`, read it for detailed component mapping guidance.
+4. Use the design references alongside the Vision text to plan the UX. The images show *what it should look like*; the Vision text explains *what it should do*.
+
+If a Figma URL is referenced in DESIGN.md, note it for the user but don't attempt to fetch it -- work from the uploaded screenshots and the text brief.
+
 ---
 
 ## Step 2: Check MCP Servers

package/commands/manage_secrets.md

@@ -0,0 +1,158 @@
+# Manage Secrets
+
+Add, update, or remove environment variables (secrets) for your deployed app. Secrets are stored encrypted on Vercel and are available to your app at runtime and build time.
+
+## Overview
+
+This command manages environment variables on your project's Vercel deployment through the Broadchurch Portal API. After any change, it automatically syncs the updated values to your local `.env` file so your dev server stays in sync with production.
+
+**Prerequisite:** The project must have a valid `broadchurch.yaml` (created during provisioning).
+
+---
+
+## Step 1: Read Configuration
+
+Read `broadchurch.yaml` from the project root.
+
+```bash
+cat broadchurch.yaml
+```
+
+**If the file does not exist:**
+
+> This project hasn't been provisioned yet. Create it in the Broadchurch Portal first.
+
+Stop here.
+
+Extract these values:
+
+- `tenant.org_id` (tenant org ID)
+- `gateway.url` (Portal Gateway URL)
+
+---
+
+## Step 2: List Current Environment Variables
+
+Fetch the current user-managed environment variables:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars"
+```
+
+Parse the JSON response. The `vars` array contains `{ key, value }` objects.
+
+Present the current state to the user:
+
+> **Environment Variables for this project:**
+>
+> | Key | Value |
+> |-----|-------|
+> | `MY_API_KEY` | `sk-abc...xyz` |
+> | `THIRD_PARTY_SECRET` | `secret_1234` |
+>
+> _(or "No environment variables set yet." if empty)_
+>
+> What would you like to do?
+>
+> 1. **Add** a new variable
+> 2. **Update** an existing variable
+> 3. **Remove** a variable
+> 4. **Done** — nothing to change
+
+Wait for the user to choose.
+
+---
+
+## Step 3: Execute the Change
+
+### If adding or updating:
+
+Ask the user for the key name and value. Key names must match `[A-Za-z_][A-Za-z0-9_]*`.
+
+```bash
+curl -sf -X PUT "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars" \
+  -H "Content-Type: application/json" \
+  -d '{"vars": {"<KEY>": "<VALUE>"}}'
+```
+
+**If the API returns 403:** The key is a platform-managed variable and cannot be modified by users.
+
+### If removing:
+
+Confirm which key to delete, then:
+
+```bash
+curl -sf -X DELETE "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars/<KEY>"
+```
+
+**If the API returns 404:** The variable doesn't exist.
+
+---
+
+## Step 4: Sync Local .env
+
+After the API call succeeds, update the local `.env` file to match.
+
+1. Read the current `.env` file
+2. Look for a `# User secrets (managed via Broadchurch Portal)` section delimiter
+3. **If the section exists:** Replace everything from that delimiter to the next blank line (or end of file) with the updated variables
+4. **If the section doesn't exist:** Append it at the end of `.env`
+
+Fetch the current full list to ensure local is in sync:
+
+```bash
+curl -sf "<GATEWAY_URL>/api/projects/<ORG_ID>/env-vars"
+```
+
+Then write the section to `.env`:
+
+```
+# User secrets (managed via Broadchurch Portal)
+KEY_ONE=value_one
+KEY_TWO=value_two
+```
+
+**Important:** Do not modify any other lines in `.env`. Only touch lines within the user secrets section.
+
+---
+
+## Step 5: Confirm and Offer Next Steps
+
+> Updated `<KEY>`:
+>
+> - Vercel (production + preview) — updated
+> - Local `.env` — synced
+>
+> **Restart your dev server** (`npm run dev`) if it's running, to pick up the change locally.
+
+If the variable name starts with `NUXT_PUBLIC_`:
+
+> **Note:** `NUXT_PUBLIC_*` variables are baked into the app at build time. The Vercel deployment will need a rebuild for the change to take effect in production. Push a commit or trigger a redeployment from the Portal.
+
+If the variable name does NOT start with `NUXT_PUBLIC_`:
+
+> This server-side variable will be available on the next request in production — no redeployment needed.
+
+Then ask:
+
+> Would you like to add, update, or remove another variable? (or type "done")
+
+If yes, go back to Step 3. If done, finish.
+
+---
+
+## Troubleshooting
+
+### "Project has no Vercel project configured"
+
+The project's Vercel integration wasn't set up during provisioning. Check the Broadchurch Portal for the project status.
+
+### API returns 403 for a key
+
+The key is platform-managed (Auth0, gateway, query server, etc.) and cannot be modified through this command. Use the Portal's Platform Services section instead.
+
+### Variable not appearing in the deployed app
+
+- **`NUXT_PUBLIC_*` vars** need a redeployment (push a commit or trigger from Portal)
+- **Server-side vars** should be available immediately — check that the key name is correct
+- Make sure you're reading the variable correctly in code: use `useRuntimeConfig()` in Nuxt, not `process.env` directly

package/commands/update_branding.md

@@ -1,123 +1,71 @@
 # Update Branding
 
-Refresh the Lovelace Brand R2 files from the canonical source repository.
+Sync the project's branding implementation with the latest Lovelace branding skill guidelines.
 
 ## Overview
 
-Aether's branding files are wholesale copies from the `moongoose/ui/news-ui` directory of the Lovelace repo. This command copies the latest versions and checks for new dependencies.
-
-**Do not hardcode any local paths.** Always ask the user for the Lovelace repo location.
+The `lovelace-branding` skill (`skills/lovelace-branding/`) is the single source of truth for Lovelace brand identity. This command reviews the project's branding implementation files and updates them to align with the skill.
 
 ---
 
-## Step 1: Ask for the Lovelace Repo Path
-
-```
-AskQuestion({
-  title: "Lovelace Repository Path",
-  questions: [
-    {
-      id: "repo-path",
-      prompt: "Where is your local clone of the Lovelace repository?",
-      options: [
-        { id: "home-lovelace", label: "~/lovelace" },
-        { id: "custom", label: "Other location (I'll specify)" }
-      ]
-    }
-  ]
-})
-```
+## Step 1: Read the Branding Skill
 
-If the user selects "Other location", ask them to provide the full path.
-
-Expand `~` to the user's home directory. Store the result as `{repo}`.
+Read the skill starting from `skills/lovelace-branding/SKILL.md`. It contains a file index that will direct you to the relevant reference files.
 
 ---
 
-## Step 2: Validate the Source Path
-
-Confirm the branding source directory exists:
+## Step 2: Review Implementation Files
 
-```bash
-ls {repo}/moongoose/ui/news-ui/BRANDING.md
-```
+Read each of the project's branding implementation files and compare against the skill guidelines:
 
-**If the file does not exist:** Tell the user the path doesn't contain the expected branding files and ask them to double-check. Stop.
+| File                              | What to check                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------- |
+| `assets/brand-globals.css`        | `:root` CSS variables match the skill's color and typography values               |
+| `assets/fonts.css`                | `@font-face` declarations match the skill's font setup                            |
+| `assets/theme-styles.css`         | Theme utility classes align with the skill's CSS patterns                         |
+| `composables/useLovelaceTheme.ts` | `themeColors` object matches the skill's color palette                            |
+| `composables/useThemeClasses.ts`  | Theme-aware utilities consistent with skill patterns                              |
+| `nuxt.config.ts`                  | Vuetify theme colors match the skill; CSS array includes all branding stylesheets |
 
-Also verify the other expected source files exist:
-
-```bash
-ls {repo}/moongoose/ui/news-ui/composables/useNewsTheme.ts
-ls {repo}/moongoose/ui/news-ui/composables/useThemeClasses.ts
-ls {repo}/moongoose/ui/news-ui/assets/theme-styles.css
-ls {repo}/moongoose/ui/news-ui/assets/fonts.css
-ls {repo}/moongoose/ui/news-ui/public/fonts/README.md
-ls {repo}/moongoose/ui/news-ui/public/LL-logo-full-wht.svg
-```
-
-Report any missing files. If critical files are missing (BRANDING.md, useNewsTheme.ts, theme-styles.css), stop. If optional files are missing (logo, fonts README), warn but continue.
+For each file, note any discrepancies between the current implementation and the skill guidelines.
 
 ---
 
-## Step 3: Copy the Branding Files
+## Step 3: Update Implementation
 
-The base source path is `{repo}/moongoose/ui/news-ui`.
+For each discrepancy found in Step 2, update the project file to align with the skill:
 
-Copy these files to their Aether destinations:
+- **CSS variables**: Update hex values, add missing variables, remove obsolete ones
+- **Color palette**: Update `themeColors` in `useLovelaceTheme.ts` to match
+- **Typography**: Update font families, weights, and fallbacks as specified by the skill
+- **Patterns**: Update theme utility classes to match the skill's CSS patterns
+- **Vuetify theme**: Update `lovelaceDark` theme colors in `nuxt.config.ts` if needed
 
-| Source (relative to base)        | Destination (relative to Aether root) |
-| -------------------------------- | ------------------------------------- |
-| `BRANDING.md`                    | `branding/BRANDING.md`                |
-| `composables/useNewsTheme.ts`    | `composables/useNewsTheme.ts`         |
-| `composables/useThemeClasses.ts` | `composables/useThemeClasses.ts`      |
-| `assets/theme-styles.css`        | `assets/theme-styles.css`             |
-| `assets/fonts.css`               | `assets/fonts.css`                    |
-| `public/fonts/README.md`         | `public/fonts/README.md`              |
-| `public/LL-logo-full-wht.svg`    | `public/LL-logo-full-wht.svg`         |
+If the skill introduces new concepts not yet implemented in the project (new CSS variable namespaces, new utility classes, new patterns), add them.
 
-For `app.vue`, extract only the `<style>` block contents (not the `<style>` tags themselves) and write them to `assets/brand-globals.css`. Read the source `app.vue`, find the content between `<style>` and `</style>`, and overwrite `assets/brand-globals.css` with that content.
+If the project has customizations that intentionally diverge from the skill (e.g., project-specific semantic colors), preserve them but note the divergence.
 
 ---
 
-## Step 4: Dependency Audit
-
-After copying, read through each copied file and check for new references that weren't present before:
+## Step 4: Check Assets
 
-1. **TypeScript imports**: Check `useNewsTheme.ts` and `useThemeClasses.ts` for any new `import` statements referencing files that don't exist in Aether.
+Compare logo and asset files in `public/` against the skill's `assets/` directory (`skills/lovelace-branding/assets/`).
 
-2. **CSS references**: Check `theme-styles.css`, `fonts.css`, and `brand-globals.css` for:
-    - `url()` paths pointing to files not in `public/`
-    - `@import` statements referencing files not in `assets/`
-
-3. **Documentation references**: Check `BRANDING.md` for references to new files (logos, assets, CSS files) that should be copied.
-
-**If new dependencies are found:**
-
-- Static assets (images, SVGs, fonts) -> copy to `public/` in the equivalent subdirectory
-- CSS files -> copy to `assets/`
-- TypeScript/JS files -> copy to `composables/` or the equivalent directory
-- Report what was copied to the user
+- Copy any new or updated SVGs/assets from the skill to `public/`
+- If existing assets differ, update them to the skill's versions
 
 ---
 
-## Step 5: Verify Integration
-
-Check that the adapter (`composables/useCustomTheme.ts`) is still compatible:
-
-1. Read `composables/useNewsTheme.ts` and check what it exports.
-2. Read `composables/useCustomTheme.ts` and confirm it re-exports the expected interface.
-3. If `useNewsTheme.ts` has added new named exports that aren't re-exported by the adapter, tell the user:
-
-> `useNewsTheme.ts` has new exports that aren't exposed through `useCustomTheme.ts`: [list them]. You may want to add these to the adapter if components need them.
-
-4. Check that `nuxt.config.ts` still includes the three CSS files:
+## Step 5: Verify
 
-```typescript
-css: ['~/assets/fonts.css', '~/assets/brand-globals.css', '~/assets/theme-styles.css'],
-```
+1. Confirm `nuxt.config.ts` CSS array still includes all branding stylesheets:
+    ```typescript
+    css: ['~/assets/fonts.css', '~/assets/brand-globals.css', '~/assets/theme-styles.css'];
+    ```
+2. Run `npm run build` to verify no compilation errors
 
 ---
 
 ## Step 6: Commit
 
-Follow the `git-support.mdc` workflow to commit the change.
+Follow the `git-support.mdc` workflow to commit the changes.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yottagraph-app/aether-instructions",
-    "version": "1.1.24",
+    "version": "1.1.26",
     "description": "Cursor rules, commands, and skills for Aether development",
     "files": [
         "rules",

package/rules/branding.mdc

@@ -3,41 +3,33 @@ description: Apply when working on visual styling, colors, typography, theming,
 alwaysApply: false
 ---
 
-# Lovelace Brand R2
+# Lovelace Branding
 
-The app follows Lovelace Brand R2 guidelines. For the full specification (color ramps, accessibility, visual effects), read `branding/BRANDING.md`.
+The `lovelace-branding` skill (`skills/lovelace-branding/`) is the single source of truth for all brand specifics -- colors, typography, patterns, assets, and usage guidelines. Read the skill before making branding decisions. Start with `SKILL.md` for the file index.
 
-## Quick Reference
+## Theme
 
-- **Theme**: Single dark theme. No light mode, no theme switching.
-- **Core colors**: Jet Black `#0A0A0A`, Pure White `#FFFFFF`, Cyber Green `#3FEA00`, Sonic Silver `#757575`
-- **Secondary colors**: Electric Blue `#003BFF`, Blaze Orange `#FF5C00`
-- **Semantic**: Amber `#FF9F0A` (warnings), Red `#EF4444` (errors)
-- **Fonts**: FK Grotesk (body), FK Grotesk Mono (headlines, buttons, code). Falls back to Inter / system-ui. See `public/fonts/README.md` for setup.
-- **Icons**: Material Design Icons (mdi) via Vuetify
+Single dark theme. No light mode, no theme switching.
 
-## Branding Files
+## Implementation Files
 
-These files are copied wholesale from the canonical branding source (`moongoose/ui/news-ui`). Update them by running `/update_branding`. Do **not** edit them in place.
+These files are project-owned. Consult the branding skill for the values and patterns they should implement.
 
-| File | Purpose |
-|---|---|
-| `branding/BRANDING.md` | Full brand specification |
-| `composables/useNewsTheme.ts` | Theme colors and CSS variable application |
-| `composables/useThemeClasses.ts` | Theme-aware class utilities |
-| `assets/theme-styles.css` | Theme CSS classes |
+| File | Role |
+|------|------|
+| `assets/brand-globals.css` | `:root` CSS variables and global typography/layout |
 | `assets/fonts.css` | `@font-face` declarations |
-| `assets/brand-globals.css` | Global CSS variables, typography, utilities |
-| `public/fonts/README.md` | Font setup instructions |
-| `public/LL-logo-full-wht.svg` | Primary logo (white, for dark backgrounds) |
+| `assets/theme-styles.css` | Theme-aware CSS utility classes |
+| `composables/useLovelaceTheme.ts` | Theme color palette and Vuetify theme activation |
+| `composables/useThemeClasses.ts` | Theme-aware class combination utilities |
 
-## Vuetify Theme
+## Integration
 
-The `lovelaceDark` Vuetify theme is defined in `nuxt.config.ts` under `vuetify.vuetifyOptions.theme`. This is the same theme used by the Broadchurch Portal. It provides Brand R2 colors to all Vuetify components automatically (primary = Cyber Green, secondary = Electric Blue, etc.). Component defaults (rounded buttons, outlined cards, etc.) are also set in `nuxt.config.ts` under `vuetify.vuetifyOptions.defaults`.
+- Use `useLovelaceTheme()` or `useThemeClasses()` in components for theme colors and class utilities.
+- The `lovelaceDark` Vuetify theme is defined in `nuxt.config.ts` under `vuetify.vuetifyOptions.theme`. It provides brand colors to all Vuetify components automatically. Component defaults are set under `vuetify.vuetifyOptions.defaults`.
+- CSS variables (`--lv-*`) and theme classes (`.theme-*`) are available globally via the stylesheets listed above.
+- `useLovelaceTheme` calls `theme.change('lovelaceDark')` to activate the Vuetify theme. This must match the theme name in `nuxt.config.ts`.
 
-## Integration
+## Updating
 
-- `composables/useCustomTheme.ts` is a thin adapter around `useNewsTheme`. Use `useCustomTheme()` or `useThemeClasses()` in components.
-- CSS variables (`--lv-green`, `--lv-black`, etc.) and theme classes (`.theme-card`, `.theme-text-primary`, etc.) are available globally.
-- `useNewsTheme` calls `theme.change('lovelaceDark')` to activate the Vuetify theme. This must match the theme name in `nuxt.config.ts`.
-- If you need to change how the branding integrates with Aether, modify the adapter -- not the branding files.
+Run `/update_branding` to sync these files with the latest branding skill guidelines. The command reads the skill, compares each implementation file against the guidelines, and updates as needed.

package/rules/design.mdc

@@ -20,7 +20,8 @@ When building from a project brief or user request, feel free to:
 
 - **Replace** `pages/index.vue` with the app's real home page
 - **Remove** any pages that don't fit the app
-- **Restructure** the navigation, layout, and branding entirely
+- **Restructure** the navigation and layout entirely
+- **Check** the branding is up to date with the `lovelace-branding` skill, and update as needed
 - **Keep** the infrastructure: `composables/`, `server/api/kv/`, `agents/`
 
 Do NOT treat the existing UI as something to preserve. Build what the
@@ -30,10 +31,23 @@ asks to keep specific parts.
 
 # Project Brief
 
-If `DESIGN.md` has a `## Vision` section, it contains the project creator's original description of what they want to build — written during project setup in the Broadchurch Portal.
+If `DESIGN.md` has a `## Vision` section, it contains the project creator's original description of what they want to build — written during project setup in the Broadchurch Portal. This can range from a single sentence to a full PRD with user stories, wireframes, and technical constraints.
 
 When a user opens the project for the first time and hasn't started building yet (the `## Status` section says "Run `/build_my_app`"), suggest running that command. If they ask "what should I build?" or similar, read the Vision section of DESIGN.md first.
 
+## Long-form briefs
+
+Users may paste full PRD or spec documents as their project brief. When the Vision section is long (500+ words), focus on extracting the MVP scope before building. Look for priority indicators, phased rollout plans, or "must-have" vs "nice-to-have" distinctions. If none exist, identify the smallest coherent feature set that demonstrates the core value. Create `design/requirements.md` to capture your extracted requirements as a working checklist.
+
+## Design references
+
+`DESIGN.md` may include a `## Design References` section with Figma URLs and/or image references. Design mockup images live in `design/references/`. When these exist:
+
+- Examine the images to understand intended layout, navigation patterns, and visual style
+- Map visual elements to Vuetify components (if a `vuetify-figma` skill exists, use it)
+- Treat design references as the "what it should look like" complement to the Vision's "what it should do"
+- Figma URLs are informational — work from the uploaded screenshots, not the live Figma file
+
 # Feature docs
 
 Feature docs are used as working documents to help a user and agent collaborate on feature implementation. A feature can be whatever size you need -- an entire page, a shared composable, or a single component.

package/skills/lovelace-branding/BRANDING.md

@@ -0,0 +1,176 @@
+# Lovelace Brand R2 Guidelines
+
+This document defines the visual identity for all Lovelace UI products (News UI, Ada Demo, etc.). It is derived from the Brand R2 review and serves as the single source of truth for colors, typography, iconography, and usage patterns.
+
+## Color Palettes
+
+### Core Palette
+
+Jet Black, Pure White, Sonic Silver, and Cyber Green are Lovelace's core brand colors.
+
+| Name         | Hex       | Usage                          |
+|--------------|-----------|--------------------------------|
+| Jet Black    | `#0A0A0A` | Primary backgrounds            |
+| Pure White   | `#FFFFFF` | Primary text on dark surfaces  |
+| Sonic Silver | `#757575` | Muted text, secondary elements |
+| Cyber Green  | `#3FEA00` | Primary accent, CTAs, success  |
+
+The palette can be extended with neutral greyscale tones ranging from Pure White `#FFF` to True Black `#000`. We use Jet Black `#0A0A0A` as our primary black for most purposes.
+
+### Secondary Colors
+
+Electric Blue and Blaze Orange are secondary colors to extend the branding.
+
+| Name          | Hex       | Usage                               |
+|---------------|-----------|-------------------------------------|
+| Electric Blue | `#003BFF` | Accent, links, finance/data         |
+| Blaze Orange  | `#FF5C00` | Warnings, highlights, secondary CTA |
+
+### Semantic Colors
+
+| Name   | Hex       | Usage    |
+|--------|-----------|----------|
+| Amber  | `#FF9F0A` | Warnings |
+| Red    | `#EF4444` | Errors   |
+
+### Color Ramps
+
+Each color has a ramp from 50 (lightest) to 950 (darkest). The `/500` value is the base brand color. Colors go lighter (lower numbers) or darker (higher numbers) depending on context.
+
+**Neutrals:**
+
+| 50      | 100      | 200      | 300      | 400      | 500      | 600      | 700      | 800      | 900      | 950      |
+|---------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|
+| #FFFFFF | #F8F8F8  | #E6E6E6  | #D5D5D6  | #B1B1B1  | #757575  | #6C6C6C  | #464646  | #222222  | #0A0A0A  | #000000  |
+
+**Green:**
+
+| 50      | 100      | 200      | 300      | 400      | 500      | 600      | 700      | 800      | 900      | 950      |
+|---------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|
+| #DDFFD1 | #BBFFA3  | #99FF75  | #78FF47  | #57FF19  | #3FEA00  | #30BC00  | #238E00  | #166100  | #0B3300  | #010500  |
+
+**Blue:**
+
+| 50      | 100      | 200      | 300      | 400      | 500      | 600      | 700      | 800      | 900      | 950      |
+|---------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|
+| #E6EBFF | #BBC7FF  | #8AA3FF  | #6C80FF  | #2E5DFF  | #003BFF  | #0230D0  | #0326A1  | #031B73  | #021146  | #010819  |
+
+**Orange:**
+
+| 50      | 100      | 200      | 300      | 400      | 500      | 600      | 700      | 800      | 900      | 950      |
+|---------|----------|----------|----------|----------|----------|----------|----------|----------|----------|----------|
+| #FFF0E6 | #FFD4B8  | #FFB78A  | #FF989C  | #FF7B2E  | #FF5C00  | #D04E02  | #A13F03  | #732F03  | #461E02  | #190801  |
+
+### Usage Proportions
+
+The proportional usage of each color to the whole (approximate):
+- Jet Black + Pure White: ~70% of surface area (dark backgrounds, white text)
+- Cyber Green: ~15% (accents, interactive elements, success states)
+- Sonic Silver: ~10% (muted text, borders, secondary elements)
+- Electric Blue + Blaze Orange: ~5% (sparingly, for specific semantic purposes)
+
+### Accessibility
+
+All color pairings must meet WCAG AA contrast ratio at a minimum. Use the color ramps to find appropriate pairings:
+- White text on Jet Black: passes AAA
+- Cyber Green on Jet Black: passes AA
+- Electric Blue on Jet Black: passes AA
+
+Reference: https://accessibleweb.com/color-contrast-checker/
+
+## Typography
+
+### Font Families
+
+| Role              | Font                | Fallbacks                              |
+|-------------------|---------------------|----------------------------------------|
+| Body / Primary    | FK Grotesk          | Inter, system-ui, sans-serif           |
+| Headlines         | FK Grotesk SemiMono | Inter, system-ui, sans-serif           |
+| Subheaders        | FK Grotesk SemiMono | Inter, system-ui, sans-serif           |
+| Buttons/Elements  | FK Grotesk Mono     | JetBrains Mono, Fira Code, monospace   |
+| Brand wordmark    | Inter               | system-ui, sans-serif                  |
+| Code/Data         | FK Grotesk Mono     | JetBrains Mono, Fira Code, monospace   |
+
+FK Grotesk is a commercial font (licensed). Font files are **not committed to git**. See `public/fonts/README.md` for setup instructions.
+
+### Type Hierarchy
+
+| Level                    | Font              | Weight  | Style      |
+|--------------------------|-------------------|---------|------------|
+| Headlines (h1)           | FK Grotesk SemiMono | Regular | Normal     |
+| Subheaders (h2, h3)      | FK Grotesk SemiMono | Regular | Normal     |
+| Body Copy                | FK Grotesk        | Regular | Normal     |
+| Body Strong / Highlighted | FK Grotesk       | Strong (700) | Normal  |
+| Buttons & UI Elements    | FK Grotesk Mono   | Regular | UPPERCASE, letter-spacing 0.05em |
+
+### CSS Variables
+
+```css
+:root {
+    --font-primary: 'FK Grotesk', 'Inter', system-ui, -apple-system, sans-serif;
+    --font-headline: 'FK Grotesk Mono', 'Inter', system-ui, sans-serif;
+    --font-brand: 'Inter', system-ui, -apple-system, sans-serif;
+    --font-mono: 'FK Grotesk Mono', 'JetBrains Mono', 'Fira Code', monospace;
+}
+```
+
+## Iconography
+
+We use the **IBM Carbon Design** icon kit -- an open-source, free icon kit with over 2,000 icons available.
+
+Library: https://carbondesignsystem.com/elements/icons/library/
+
+In practice, we currently use Material Design Icons (mdi) via Vuetify. Carbon icons can be adopted incrementally.
+
+## Logo
+
+The primary logo is the Lovelace wordmark with the circular green-dot badge:
+- **White version** (for dark backgrounds): `LL-logo-full-wht.svg`
+- Located in `public/LL-logo-full-wht.svg`
+
+## Visual Effects (Optional)
+
+These effects can be applied sparingly for branded sections:
+
+- **Grid pattern**: Subtle grid lines at 20px intervals
+- **Dot pattern**: Punch-card aesthetic with radial dots at 16px intervals
+- **Glow effects**: Colored box-shadows (green, orange, blue) at 0.3 opacity
+- **Text glow**: Green text-shadow for emphasis
+
+## CSS Variable Reference
+
+All Brand R2 CSS variables are defined in `app.vue` under `:root`:
+
+```css
+:root {
+    /* Core */
+    --lv-black: #0A0A0A;
+    --lv-surface: #141414;
+    --lv-surface-light: #1E1E1E;
+    --lv-white: #FFFFFF;
+    --lv-silver: #757575;
+
+    /* Primary */
+    --lv-green: #3FEA00;
+    --lv-green-dim: #30BC00;
+    --lv-green-light: #57FF19;
+
+    /* Secondary */
+    --lv-orange: #FF5C00;
+    --lv-orange-dim: #D04E02;
+    --lv-blue: #003BFF;
+    --lv-blue-dim: #0230D0;
+    --lv-blue-light: #2E5DFF;
+
+    /* Semantic */
+    --lv-yellow: #FF9F0A;
+    --lv-finance-blue: #003BFF;
+}
+```
+
+## Implementation Notes
+
+- The News UI uses a single dark theme ("brand") defined in `composables/useNewsTheme.ts`
+- Theme-aware CSS utility classes are in `assets/theme-styles.css`
+- The `useThemeClasses` composable provides pre-built class combinations for components
+- Vuetify is configured with `defaultTheme: "dark"` in `nuxt.config.ts`