sdg-agents 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdg-agents",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Structured working protocol and engineering rules for AI agents. Works with Claude Code, Antigravity, Codex, and others.",
   "type": "module",
   "main": "./src/engine/bin/index.mjs",

package/src/assets/instructions/core/ui/design-thinking.md

@@ -114,61 +114,51 @@ Then generate the full scale using the **OKLCH Progression Formula**:
 
 | Step | L (Lightness) | C (Chroma) | Notes                               |
 | ---: | :------------ | :--------- | :---------------------------------- |
-|   50 | `97%`         | `0.02`     | Near-white background tint          |
-|  100 | `93%`         | `0.05`     | Very light surface tint             |
-|  200 | `87%`         | `0.08`     | Light border / subtle dividers      |
-|  300 | `79%`         | `0.11`     | Soft accent                         |
-|  400 | `68%`         | `0.13`     | Light mode hover state              |
-|  500 | `58%`         | `0.15`     | **Primary action** (buttons, links) |
-|  600 | `48%`         | `0.14`     | Light mode hover on primary-500     |
-|  700 | `38%`         | `0.12`     | Strong accent                       |
-|  800 | `29%`         | `0.09`     | Dark surface tint                   |
-|  900 | `21%`         | `0.06`     | Near-black background tint          |
-
-> The Hue (H) is **fixed** across the entire scale. Only L and C change.
-> To switch the brand color: **change only H**.
+|   50 | `98%`         | `0.01`     | Near-white background tint          |
+|  100 | `96%`         | `0.03`     | Very light surface tint             |
+|  200 | `90%`         | `0.06`     | Light border / subtle dividers      |
+|  300 | `82%`         | `0.09`     | Soft accent                         |
+|  400 | `72%`         | `0.12`     | Light mode hover state              |
+|  500 | `60%`         | `0.15`     | **Primary action** (buttons, links) |
+|  600 | `50%`         | `0.14`     | Light mode hover on primary-500     |
+|  700 | `40%`         | `0.12`     | Strong accent                       |
+|  800 | `25%`         | `0.09`     | Dark surface tint                   |
+|  900 | `15%`         | `0.05`     | Near-black background tint          |
+
+> **Vibe Control**: For a **Vibrant** look, keep Chroma (C) at `0.15` for steps 400-600. For a **Muted** look, reduce C to `0.08` across the entire scale. Default to **Muted** for Premium SaaS.
 
 </rule>
 
 ---
 
-## Phase 0.2 — Light / Dark Token Inversion
+## Phase 0.2 — The Elevation Stack (Deep Theme Balance)
 
-<rule name="LightDarkInversion">
+<rule name="ElevationStack">
 
 > [!IMPORTANT]
-> **The most common agent failure: applying light-mode hover logic to dark mode.**
+> **Avoid "Floating Darkness".** Dark mode surface logic must reflect physical elevation: as an object gets closer to the light source (user), it gets **lighter**, not darker.
 
-Dark mode inverts the Lightness axis. The same token value that reads as "lighter" in light mode reads as "wrong direction" in dark mode.
+### Surface Mapping
 
-### The Inversion Law
+| Layer          | Role               | Light Mode (Zinc)     | Dark Mode (Zinc) |
+| :------------- | :----------------- | :-------------------- | :--------------- |
+| **S0** (Base)  | Page Background    | `50` or `White`       | `950` or `Black` |
+| **S1** (Inner) | Sidebars, Sections | `100`                 | `900`            |
+| **S2** (Card)  | Floating Elements  | `White` + Shadow      | `800`            |
+| **S3** (Pop)   | Modals, Tooltips   | `White` + Deep Shadow | `700`            |
 
-| Context    | Base  | Action (hover/active) | Direction  |
-| :--------- | :---- | :-------------------- | :--------- |
-| Light mode | `500` | `600`                 | Go darker  |
-| Dark mode  | `500` | `400`                 | Go lighter |
+### The Hover Law (Inversion)
 
-```html
-<!-- Correct — both themes use the right direction -->
-<button class="bg-primary-500 hover:bg-primary-600 dark:hover:bg-primary-400">Ação</button>
-```
+| Context    | Base | Action | Direction  | Value Delta |
+| :--------- | :--- | :----- | :--------- | :---------- |
+| Light mode | `S2` | `S1`   | Go Darker  | L-5%        |
+| Dark mode  | `S2` | `S3`   | Go Lighter | L+10%       |
 
 ```html
-<!-- ❌ Wrong — dark hover goes darker, feels invisible -->
-<button class="bg-primary-500 hover:bg-primary-600 dark:hover:bg-primary-600">Ação</button>
+<!-- Correct — Dark mode "elevates" on hover by getting lighter -->
+<div class="bg-zinc-800 hover:bg-zinc-700 transition-colors">Card</div>
 ```
 
-### Why this happens (mental model)
-
-In light mode, the page background is near-white → `primary-500` sits on a light plane → hover must move toward the dark end to create contrast.
-
-In dark mode, the page background is near-black → `primary-500` sits on a dark plane → hover must move toward the light end to surface.
-
-The OKLCH Lightness axis makes this mechanical:
-
-- **Light hover** = lower L → `600` (L=48%)
-- **Dark hover** = higher L → `400` (L=68%)
-
 </rule>
 
 ---
@@ -297,6 +287,31 @@ Every interface uses **exactly 2 font families** — one Display, one Body. No e
 
 ---
 
+## Phase 0.6 — Component Nesting (Concentricity)
+
+<rule name="Nesting">
+
+Nested elements (cards inside sections, inputs inside cards) must maintain visual logic.
+
+### 1. The Concentric Radius Rule
+
+Outer container and inner child must share a common center.
+`Inner Radius = Outer Radius - Padding`.
+
+- Outer: `rounded-2xl` (16px) | Padding: `p-4` (16px) → Inner: `rounded-none` (0px)
+- Outer: `rounded-2xl` (16px) | Padding: `p-2` (8px) → Inner: `rounded-lg` (8px)
+
+### 2. Border Hierarchy
+
+To prevent "Wireframe Look", adjust border visibility based on depth.
+
+- **S1/S2 Boundary**: `border-border/40` (subtle)
+- **S2/Action Boundary**: `border-primary/20` (contextual)
+
+</rule>
+
+---
+
 ## Agent Self-Declaration (Required Output)
 
 Before writing any UI code, the agent MUST declare:

package/src/assets/instructions/core/ui/presets.md

@@ -25,9 +25,9 @@ Each preset MUST define:
 - Personality: Modular dashboard
 - Typography: Sans (UI) + Serif (highlights)
 - Grid: `grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 auto-rows-[minmax(180px,1fr)]`
-- Cards: `flex flex-col h-full transition-colors hover:border-primary/20`
+- Cards: `S2` (e.g. `bg-card`)
 - Radius: `rounded-xl / rounded-2xl`
-- Density: Medium
+- Density: Medium (`gap-4` to `gap-6`)
 - States:
   - hover: `border-primary/20`
   - focus: `ring-2 ring-primary`
@@ -39,7 +39,7 @@ Each preset MUST define:
 
 - Personality: Layered, depth-driven
 - Typography: Sans clean
-- Surface: `bg-card/60 backdrop-blur-xl`
+- Surface: `S2 / S3` (e.g. `bg-card/60 backdrop-blur-xl`)
 - Borders: `border-border/30`
 - Radius: `rounded-2xl`
 - Elevation: Blur + subtle shadow
@@ -143,7 +143,18 @@ Each UI must declare:
 - `default + mono` → developer tools (Palette: Zinc monochromatic)
 - `bento + brutalism` → experimental layouts (Palette: any high-C primary)
 
-> For token generation and light/dark inversion rules for each palette, see [design-thinking.md](./design-thinking.md).
+> For token generation and light/dark inversion rules, see the **Elevation Stack (S0-S3)** in [design-thinking.md](./design-thinking.md).
+
+---
+
+## C4. The Nesting Pattern (Anilhamento)
+
+Presets with structural containers (BENTO, GLASS, CLEAN) MUST follow the **Elevation Stack** when nesting components:
+
+1. **Base**: `S0` (Page Background)
+2. **Container**: `S1` or `S2`
+3. **Child Element**: Move one layer up (e.g., child of `S2` is `S3`).
+4. **Contrast**: Apply the **S1/S2 Boundary** border rules from [design-thinking.md](./design-thinking.md).
 
 ---
 

package/src/assets/instructions/core/ui/standards.md

@@ -90,6 +90,7 @@ Every interactive UI MUST implement:
   - must meet WCAG AA (4.5:1 for normal text, 3:1 for large text)
   - avoid low-contrast combinations (e.g. muted on muted)
   - OKLCH quick check: Lightness delta between text and background must be ≥ 40 percentage points (e.g., text at L=55% on background at L=97% → delta=42% ✔)
+  - **Contextual Contrast**: Secondary text (muted) on `S1/S2` surfaces should maintain a Lightness delta of ≥ 25% (e.g. text L=70% on surface L=95%).
   - for token generation ensuring compliant contrast, see [design-thinking.md](./design-thinking.md)
 
 - ARIA:
@@ -135,6 +136,23 @@ Every interactive UI MUST implement:
 
 ---
 
+## Rule: Density & Spacing (L1–L4)
+
+<rule name="Density">
+
+Spacing must follow a consistent hierarchy to avoid visual noise.
+
+| Level  | Role                     | Gap/Padding | Value (Tailwind)        |
+| :----- | :----------------------- | :---------- | :---------------------- |
+| **L1** | Internal (Button/Icon)   | `4–8px`     | `gap-1`, `gap-2`, `p-2` |
+| **L2** | Siblings (Items in Card) | `16–20px`   | `gap-4`, `p-4`, `p-5`   |
+| **L3** | Sections (Card in Grid)  | `24–40px`   | `gap-6`, `gap-10`       |
+| **L4** | Global (Page containers) | `64px+`     | `py-16`, `px-6`         |
+
+</rule>
+
+---
+
 ## Reference Links
 
 - [design-thinking.md](./design-thinking.md) — Phase 0: palette setup, OKLCH token generation, light/dark inversion, aesthetic direction

package/src/assets/instructions/templates/workflow.md

@@ -140,8 +140,8 @@ On every request, classify intent before acting:
 ### END Checklist (mandatory — execute in order, mark each before proceeding)
 
 - [ ] **SUMMARIZE** — one sentence per completed PLAN task written in response
+- [ ] **CHANGELOG** — Prepare your technical narrative in the `CHANGELOG.md` under `## [Unreleased]`. This MUST be done before bumping.
 - [ ] **BUMP** — run \`npm run bump <feat|fix>\` to promote CHANGELOG and package.json version. Skip if not applicable.
-- [ ] **CHANGELOG** — Verify [Unreleased] content was promoted. Append any manual notes if needed.
 - [ ] **BACKLOG: tasks.md** — all completed tasks moved to `## Done` with `[DONE]` status
 - [ ] **BACKLOG: context.md** — \`## Now\` updated with next objective or cleared
 - [ ] **KNOWLEDGE** — Log any patterns, findings, or rework discovered during this cycle. Update \`.ai-backlog/learned.md\` (for successful feats) or \`.ai-backlog/troubleshoot.md\` (for fixed incidents). Curate stale or irrelevant items.