# DO-NOT-CHANGE-EVER.md
## Apex Motion Engine — Constitutional Specification
### Locked 2026-05-30. Every Sonnet worker, every Cloudflare Worker, every human dev reads this VERBATIM before generating anything.
---
> This file is the law. It cannot be amended silently, overridden locally, or "temporarily"
> bypassed for a deadline. Every violation ships brand drift. Brand drift compounds.
> Compounded drift broke lesser products. This file exists so it never breaks ours.
>
> IF YOUR GENERATED OUTPUT CONTRADICTS ANYTHING IN THIS FILE, YOUR OUTPUT IS WRONG.
> Throw it away and regenerate with this file re-read first.
---
## SECTION 1 — FONTS (LOCKED)
### Permitted Typefaces
| Role | Family | Weight Range | Notes |
|---|---|---|---|
| Display headlines | Inter Tight | 700, 800, 900 | All hero text, section titles, stat readouts |
| Body / UI copy | Inter Tight | 400, 500, 600 | Labels, paragraphs, captions, tooltips |
| Mono / technical | JetBrains Mono | 400, 500, 700 | Counters, telemetry, code, ticker labels, timestamps |
| Cinematic display | Fraunces | 300, 400, 700, 900 | Variable (opsz 9-144). Cinematic moment headlines, luxury editorial openers, chapter title cards, pull-quotes. Large-scale dramatic text only. |
| Editorial body | Crimson Pro | 300, 400, 600, 700 | Extended editorial body copy, investor letters, manifesto sections, credential bios. Never for short UI labels. |
| Geometric sans alt | Space Grotesk | 300, 400, 500, 600, 700 | Dashboard section headings, metric card labels, UI variety. More personality than Inter Tight. Never replaces Inter Tight as default. |
| Secondary mono | DM Mono | 300, 400, 500 | Compact inline code, micro-telemetry, secondary technical labels where JetBrains Mono is too dominant. Never replaces --font-mono. |
### Load Order (CDN — always use these exact URLs)
```html
```
### CSS Root Declarations (required in every component)
```css
:root {
/* Locked — DO NOT change or remove */
--font-display: 'Inter Tight', system-ui, -apple-system, sans-serif;
--font-body: 'Inter Tight', system-ui, -apple-system, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', ui-monospace, monospace;
/* Extended brand fonts (approved 2026-05-30) */
--font-cinematic: 'Fraunces', 'Georgia', serif;
--font-editorial: 'Crimson Pro', 'Georgia', serif;
--font-geometric: 'Space Grotesk', system-ui, -apple-system, sans-serif;
--font-mono-alt: 'DM Mono', 'JetBrains Mono', ui-monospace, monospace;
}
body {
font-family: var(--font-body);
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
```
### Font Expansion Rule
The approved brand typeface set as of 2026-05-30 is: Inter Tight, JetBrains Mono, Fraunces, Crimson Pro, Space Grotesk, DM Mono. These 6 fonts are the only legal typefaces in any Apex Motion Engine output.
Future typeface additions (e.g., Editorial New, Migra, Söhne, Mona Sans, Druk Wide) are allowed ONLY after explicit written approval from Ben. Never added silently, never assumed, never "temporarily." Until Ben approves and this document is updated, no font outside the approved set of 6 may appear in any output.
---
## SECTION 2 — PALETTE (COOL-SPECTRUM ONLY, LOCKED)
The entire Apex palette lives in the violet-indigo-blue-obsidian-pearl range. Nothing outside this range is ever legal. When in doubt, go darker or more desaturated -- never warmer.
### Primary Brand
```css
:root {
--apex-primary: #635bff; /* Apex violet — buttons, CTAs, key accents */
--apex-hover: #5851e6; /* Hover state for --apex-primary */
}
```
### Brand Gradient (the canonical Apex gradient, never altered)
```css
:root {
--apex-gradient: linear-gradient(135deg, #7a73ff 0%, #635bff 35%, #4f46e5 65%, #2563eb 100%);
}
/* Usage: applied to text via background-clip, to borders, to button fills, to orb glows */
```
### Accent Variants
```css
:root {
--accent-lilac: #a8a3ff; /* Light violet — subtle highlights, secondary text emphasis */
--accent-soft: #b8b3ff; /* Soft violet — icon fills, chip labels */
--accent-pale: #cdd2ff; /* Pale violet-blue — dividers, ghost borders, disabled text */
--accent-royal: #4f7dff; /* Royal blue — data-vis accents, chart lines, secondary CTAs */
--accent-electric: #2563eb; /* Electric blue — gradient terminus, deep highlights */
}
```
### Obsidian Backgrounds (dark-mode, all components default dark)
```css
:root {
--bg-void: #06081a; /* Deepest background — page root, full-bleed hero sections */
--bg-abyss: #08091a; /* Slightly lighter — section containers */
--bg-deep: #0a0c1e; /* Standard card/panel background */
--bg-navy: #0a0e1f; /* Elevated surface — modals, drawers */
}
```
### Surface Tints (light-mode elements, use sparingly)
```css
:root {
--surface-pearl: #f4f5f8; /* Pearl — lightest surface, stat backgrounds on light themes */
--surface-white: #fafbfc; /* Off-white surface */
--surface-mist: #f7f8fa; /* Mist — card hover on light themes */
--surface-warm: #fdfcfb; /* Near-white — almost never used, only when forced */
}
```
### Mid-Tones (text, borders, dividers on dark backgrounds)
```css
:root {
--mid-deep: #1a1f36; /* Deepest mid — card borders, hairline dividers */
--mid-slate: #3c4257; /* Card-border, input outline, inactive tab */
--mid-muted: #697386; /* Muted label text, helper text, placeholder */
--mid-soft: #8792a2; /* Softer muted text — secondary captions */
--mid-light: #a4a9bd; /* Light mid — secondary body text on dark bg */
}
```
### Full CSS Custom Property Block (paste this into every component's :root)
```css
:root {
/* Primary */
--apex-primary: #635bff;
--apex-hover: #5851e6;
--apex-gradient: linear-gradient(135deg, #7a73ff 0%, #635bff 35%, #4f46e5 65%, #2563eb 100%);
/* Accents */
--accent-lilac: #a8a3ff;
--accent-soft: #b8b3ff;
--accent-pale: #cdd2ff;
--accent-royal: #4f7dff;
--accent-electric: #2563eb;
/* Backgrounds */
--bg-void: #06081a;
--bg-abyss: #08091a;
--bg-deep: #0a0c1e;
--bg-navy: #0a0e1f;
/* Surfaces */
--surface-pearl: #f4f5f8;
--surface-white: #fafbfc;
--surface-mist: #f7f8fa;
--surface-warm: #fdfcfb;
/* Mid-tones */
--mid-deep: #1a1f36;
--mid-slate: #3c4257;
--mid-muted: #697386;
--mid-soft: #8792a2;
--mid-light: #a4a9bd;
/* Fonts — locked */
--font-display: 'Inter Tight', system-ui, sans-serif;
--font-body: 'Inter Tight', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', ui-monospace, monospace;
/* Fonts — extended (approved 2026-05-30) */
--font-cinematic: 'Fraunces', 'Georgia', serif;
--font-editorial: 'Crimson Pro', 'Georgia', serif;
--font-geometric: 'Space Grotesk', system-ui, sans-serif;
--font-mono-alt: 'DM Mono', 'JetBrains Mono', ui-monospace, monospace;
}
```
### Color Expansion Rule
New colors follow the same rule as fonts: explicit written approval from Ben, then update this document. No hex values outside the cool-spectrum range are ever legal without that approval.
---
## SECTION 3 — BRAND ASSETS (LOCKED URLS AND STRINGS)
### Orb / Logo
| Asset | URL | Usage |
|---|---|---|
| Apex Logo (256px PNG) | `https://pub-86e919b2b9b945e7b0ce2253d77de22b.r2.dev/apex-logo-256.png` | All orb placements, hero sections, watermarks, email headers |
The logo URL is an R2 public bucket. It does not expire. Never use a local path, a different host, or a CSS-drawn substitute. Pre-blurred radial gradient glows behind the orb are fine -- CSS-drawn orb replacements are not.
```html
```
### Email Address (SINGULAR domain, NO trailing S)
```
info@apexopsystem.com
```
Every component, every template, every generated page that includes contact information uses exactly this string. Never `info@apexopsystems.com`, never `hello@`, never any other alias unless Ben explicitly adds it to this document.
### Website URL (PLURAL domain, WITH trailing S)
```
apexopsystems.com
```
Every external-facing URL, every footer copyright link, every "visit" reference uses exactly this domain. Never `apexopsystem.com` (that is the email domain, not the website domain). The distinction is intentional and permanent.
| String | Value |
|---|---|
| Contact email | `info@apexopsystem.com` (singular — no trailing s) |
| Website | `apexopsystems.com` (plural — with trailing s) |
| Full site URL | `https://apexopsystems.com` |
---
## SECTION 4 — FORBIDDEN (REJECTION ON SIGHT)
If any of the following appear in a generated component, the component FAILS the audit immediately. No exceptions. No partial credit. Fix and resubmit.
### 4.1 — Forbidden Colors
The following colors and any hex, rgb, hsl, named CSS value, or Tailwind class that maps to them are forbidden in all rendered output:
| Forbidden | Examples of what is also forbidden |
|---|---|
| Red | `#ff0000`, `#ef4444`, `#dc2626`, `#f87171`, `red`, `crimson`, `tomato` |
| Green | `#22c55e`, `#16a34a`, `#4ade80`, `green`, `emerald`, `lime`, `teal` (warm teal) |
| Amber | `#f59e0b`, `#d97706`, `amber`, `yellow-500`, `orange-400` |
| Orange | `#f97316`, `#ea580c`, `orange`, `tangerine` |
| Yellow | `#eab308`, `#fbbf24`, `yellow`, `gold` |
| Magenta | `#ec4899`, `#db2777`, `magenta`, `fuchsia` |
| Pink | `#f472b6`, `#fb7185`, `pink`, `hot pink` |
| Rose | `#fb7185`, `#f43f5e`, `rose` |
| Salmon / Peach / Coral | any hex value with dominant red+orange channel |
Status indicators specifically: use these substitutes.
- Success / passing / active: `--apex-primary` (#635bff) or `--accent-lilac` (#a8a3ff)
- Error / failing / stuck: `--mid-slate` (#3c4257) or a grey-muted treatment
- Warning / caution: `--accent-pale` (#cdd2ff) or dim the primary
- Live / recording state: a brighter purple pulse using `--apex-primary` at elevated opacity
### 4.2 — Forbidden Typography Characters
| Character | Unicode | Why |
|---|---|---|
| Em-dash | U+2014 (--) | Looks AI-generated. Never in any user-facing copy. Use a comma, period, or sentence break instead. |
| En-dash | U+2013 (-) | Same rule. Never in copy. Use a hyphen in ranges (e.g., "5-10") only if unavoidable. |
| Smart / curly quotes | U+2018 U+2019 U+201C U+201D | Let the browser handle typographic quotes. Never hardcode these in copy strings. |
| Emoji of any kind | Various | No emoji anywhere in user-facing copy, labels, headings, buttons, or status text. Use SVG icons exclusively. |
### 4.3 — Forbidden CSS/Animation Techniques
| Technique | Why It Is Banned |
|---|---|
| `filter: blur(...)` animated (in a `@keyframes`, GSAP tween, or transition) | Forces a new stacking context every frame. Destroys compositing. Paint killer on mobile. Causes jank at any scroll speed. |
| `backdrop-filter` animated (any property change in an animation or transition) | Same reason as above. Constant repaint of everything behind the element. |
| `filter: blur(...)` in persistent CSS at all | Pre-blurred radial gradient overlays (`background: radial-gradient(...)`) are fine. A CSS rule that applies `filter: blur` to a DOM element that stays in the DOM is not. If you need a blurry background shape, render it as a gradient or a pre-blurred PNG asset. |
| `transition: all` on any animated element | Catches unintended properties. Always specify the exact property: `transition: transform 0.3s ease, opacity 0.3s ease`. |
| `position: fixed` inside a `transform`ed ancestor | Breaks fixed positioning. GSAP ScrollTrigger pinning uses transforms. Never put fixed children inside pinned containers. |
### 4.4 — Forbidden Code Patterns
| Pattern | Why | Fix |
|---|---|---|
| Hardcoded magic numbers without an explanation comment | Impossible for the next worker to know what `1440`, `0.72`, or `3200` means | Add: `/* 1440px = max-width design breakpoint */` |
| `setInterval(fn, n)` without a stored reference and `clearInterval` call | Leaks timers. Accumulates on navigation or component unmount. Kills mobile performance over time. | `const timer = setInterval(fn, n); /* cleanup: clearInterval(timer) in destroy() */` |
| `addEventListener` without a documented cleanup path | Leaks event listeners. Accumulates on repeated component init. | Document the corresponding `removeEventListener` call in the component's `destroy()` or `cleanup()` function. |
| Inline `style=""` with pixel values for layout (except GSAP transforms) | Hard to audit, hard to override, hard to theme. | Use CSS custom properties and class names. Only exception: GSAP-set transform values (`style="transform: ..."`) which are controlled programmatically. |
| `console.log`, `console.warn`, `console.error` calls in shipped code | Every shipped component must render console-clean. | Remove all debug logs before submitting for audit. |
---
## SECTION 5 — REQUIRED TECHNIQUES
Every component that uses GSAP animation MUST implement the following patterns. No exceptions.
### 5.1 — GSAP Opacity: Use `autoAlpha`, Not `opacity`
```javascript
// WRONG — leaves display:block on invisible elements, breaks tab order and hit-testing
gsap.to(element, { opacity: 0 });
// CORRECT — sets both opacity:0 AND visibility:hidden, removes from interaction tree
gsap.to(element, { autoAlpha: 0 });
gsap.from(element, { autoAlpha: 0 }); // also correct for entrances
```
Use `autoAlpha` on all containers, overlays, panels, and any element that fully appears or disappears. Use plain `opacity` only when you intentionally want the element to remain in the interaction tree at zero opacity.
### 5.2 — GPU Compositing: `force3D: true` on Transform-Heavy Tweens
```javascript
// Required on any tween using x, y, scale, rotation, or skew on a significant element
gsap.to(element, {
x: 200,
y: -50,
scale: 1.2,
force3D: true, /* <-- promotes to GPU compositor layer for the duration of the tween */
duration: 0.6,
ease: 'power3.out'
});
```
Apply `force3D: true` to any tween on a card, hero element, particle, or any element that moves during scroll. This is required, not optional.
### 5.3 — CSS Layer Promotion: `will-change: transform`
```css
/* Apply to any CSS layer that will be animated by GSAP or CSS transitions */
.animated-card,
.scroll-panel,
.particle-layer,
.hero-headline,
.counter-display {
will-change: transform; /* Promotes to compositor layer pre-emptively */
}
/* Remove will-change after animation completes if the element will be static for > 2s */
/* GSAP autoRemoveChildren handles this for timelines */
```
### 5.4 — Scroll Normalization (required for all scroll-driven pages)
```javascript
// Must appear in the boot/init function of any page using ScrollTrigger
ScrollTrigger.normalizeScroll(true);
/* Normalizes scroll behavior across iOS rubber-band, touch devices, and desktop.
Prevents jank on mobile ScrollTrigger sequences. */
```
### 5.5 — Lag Smoothing (required for all pages using GSAP ticker)
```javascript
// Must appear at boot, before any ScrollTrigger or animation is registered
gsap.ticker.lagSmoothing(500, 33);
/* First arg: max ms lag before smoothing kicks in (500ms = half a second).
Second arg: adjusted delta cap in ms (33ms = ~30fps floor).
Prevents the "catch-up avalanche" after a browser tab goes inactive. */
```
### 5.6 — Particle Cap
```
Maximum simultaneous particles in any single scene: 80
```
This is a hard ceiling. Not a guideline. Not "80 unless it looks cool." 80. Above 80 simultaneous particles, mobile CPUs fall below 30fps. If a scene concept requires more visual density, achieve it with pre-rendered CSS gradients, SVG overlays, or layered blur-free backgrounds -- not live DOM particles.
---
## SECTION 6 — STRUCTURAL RULES
### 6.1 — File Structure: Every Component Ships These 5 Files
No component is considered complete until all 5 files exist and are committed.
```
//
component.html # Self-contained preview. Opens in a browser with zero server. All assets inlined or CDN-linked.
component.css # Extracted styles. Namespaced with component ID prefix to prevent collisions.
component.js # Extracted logic. Must expose init() and destroy() functions.
prompt.md # The exact prompt that would regenerate this component from scratch. Used by Protocol B.
README.md # What this component does, when to use it, what slots/props it accepts.
metadata.json # Structured metadata (see schema below).
```
### 6.2 — metadata.json Schema (required for every component)
```json
{
"id": "BEAT-01",
"category": "scroll-beats",
"title": "Founding Seat Boot",
"description": "Chrome orb entrance + headline cascade + scroll cue. The canonical welcome beat.",
"status": "pass",
"created": "2026-05-30",
"passed": "2026-05-30",
"gsap_features": ["ScrollTrigger", "SplitText", "autoAlpha", "force3D"],
"particle_peak": 0,
"console_clean": true,
"mobile_tested": true,
"tags": ["hero", "entrance", "orb", "headline"]
}
```
### 6.3 — Isolation Requirement
Every `component.html` must work when opened directly in a browser via `file://` or a simple static server. It must not depend on a parent page, a running backend, or any local file outside its own directory. All GSAP + font CDN links are loaded from the component file itself.
### 6.4 — Every Sonnet Worker Reads This File First
The worker prompt must begin with:
```
BEFORE GENERATING ANYTHING, READ THE FOLLOWING CONSTITUTION IN FULL:
[contents of DO-NOT-CHANGE-EVER.md pasted verbatim]
You are now cleared to generate. Every rule above applies to every line you write.
If any line of your output would violate a rule above, throw it away and rewrite it.
```
This is not optional. If a worker is dispatched without this preamble, any output it produces is considered untrusted and must go to `_pending/` for auditor review before it can be promoted.
### 6.5 — Builder + Auditor Loop (mandatory for every change)
No component reaches `pass` status via a single-agent pass. The loop is:
1. Builder worker generates the component.
2. Auditor worker reads this file, then reads the generated output, then produces a pass/fail/fix report.
3. If the auditor produces a fix list, the builder applies every fix.
4. Auditor re-reads and re-checks.
5. Repeat until auditor issues a clean PASS.
6. Only after an auditor-issued clean PASS does the component proceed to Ben for review.
Skipping the auditor loop to ship faster is not allowed. The auditor loop exists precisely because "I think it looks right" is not a quality bar.
---
## SECTION 7 — PROTOCOL A: SAFE-WRITE (Adding a New Component to the Library)
Use Protocol A when generating a completely new component that does not derive from an existing one.
### Steps
1. The Cloudflare Worker receives a generation job with a prompt and job UUID.
2. The Sonnet worker picks up the job.
3. The worker reads this file (DO-NOT-CHANGE-EVER.md) verbatim before generating one line of output.
4. The worker generates all 5 required files into `_pending//`.
5. The worker runs a self-audit pass: does the output violate any rule in this file? If yes, fix it before committing.
6. The auditor worker reads this file and audits all 5 generated files. It produces a PASS or a fix list.
7. If fix list: builder applies every fix. Return to step 5.
8. When auditor issues PASS: the component is staged for Ben review. A NEW card appears in the library UI with a PENDING badge.
9. Ben reviews in the library UI. He presses PASS, FAIL, or EDIT.
10. If PASS: Protocol A completes. Move to promotion (see Section 9).
11. If FAIL: Protocol A terminates. Move to `_trash//`. Log failure reason in `_trash//FAIL-REASON.md`.
12. If EDIT: Ben records a voice note. Whisper transcribes. Transcript becomes the new regenerate prompt. Restart from step 1 with the new prompt, creating a new UUID. This is now Protocol B.
---
## SECTION 8 — PROTOCOL B: SAFE-DERIVE (Creating a Variant from an Existing Component)
Use Protocol B when creating a variation of an existing canonical component (e.g., a leaderboard with a different entrance animation, a counter with a different digit style, a hero with a different headline animation).
### Steps
1. Identify the source component: `//`. This is the parent.
2. Read the parent's `prompt.md`. This is the base prompt.
3. Read the parent's `component.html`, `component.css`, `component.js` in full.
4. Read this file (DO-NOT-CHANGE-EVER.md) verbatim.
5. Compose the variant prompt: parent prompt + the specific delta from Ben's EDIT voice note (or from the generation job).
6. Generate all 5 required files into `_pending//`. The new component's `prompt.md` must include: the parent's full prompt, the delta instruction, and the resulting full regeneration prompt.
7. Follow steps 5-12 of Protocol A.
### Rules for Variants
- A variant MUST be distinguishably different from its parent. Changing a single color value does not constitute a variant.
- A variant inherits all rules from this document. It does not inherit exceptions from its parent (there are no exceptions).
- A variant's `metadata.json` must include a `"derived_from": ""` field.
---
## SECTION 9 — PASS / FAIL / EDIT CONTRACT
### PASS
When Ben presses PASS on a pending component:
1. Move files from `_pending//` to `//`.
- The auto-incrementing ID is zero-padded to 4 digits: `BEAT-0021`, `COUNTER-0004`, etc.
- The category folder is determined by the component's `metadata.json` `"category"` field.
2. Update `metadata.json`: set `"status": "pass"` and `"passed": ""`.
3. Commit all 5 files to GitHub with message: `add(): []`
4. Push to main.
5. Trigger library UI refresh. The component appears in its category carousel with a NEW pulse badge (badge expires after 48 hours).
6. The component is now part of the canonical org library. All future workers may derive from it via Protocol B.
### FAIL
When Ben presses FAIL on a pending component:
1. Move files from `_pending//` to `_trash//`.
2. Create `_trash//FAIL-REASON.md` with: the original prompt, Ben's failure note (transcribed if voice), and the specific rules violated.
3. Commit with message: `trash(): FAIL — `
4. Do NOT delete the files. The trash is a learning corpus for future workers.
5. Future generation jobs for similar prompts must include the FAIL-REASON.md as negative context.
### EDIT
When Ben presses EDIT on a pending component:
1. The recording panel opens. Ben records a voice note describing the change.
2. Whisper transcribes the note.
3. The transcript is appended to the original prompt as a delta instruction.
4. A new generation job is created with a new UUID.
5. The new job follows Protocol B (the current pending component is the parent).
6. The original pending component stays in `_pending//` until the new variant is reviewed. If the new variant gets PASS, the original is moved to `_trash//` with reason "superseded by ". If the new variant also gets EDIT or FAIL, the process repeats.
---
## SECTION 10 — CONSOLE-CLEAN MANDATE
Every shipped component (status: pass) must render with zero console output in Chrome 120 or later.
### The Three Categories of Violation
| Violation | Example | Severity |
|---|---|---|
| Console error | `Uncaught TypeError`, `Failed to load resource`, `Cannot read properties of null` | Blocks PASS. Must fix. |
| Console warning | `Each child in a list should have a unique key`, GSAP license warning (unlicensed club plugins), deprecated API usage | Blocks PASS. Must fix or suppress with documented reason. |
| Deprecation notice | `OffscreenCanvas is deprecated`, ` is deprecated in ` | Blocks PASS. Must update to current API. |
### Auditor Verification Step
Before issuing any PASS, the auditor worker must confirm:
1. All script src URLs resolve (no 404s).
2. All font URLs resolve.
3. The orb image URL (`https://pub-86e919b2b9b945e7b0ce2253d77de22b.r2.dev/apex-logo-256.png`) resolves.
4. GSAP is loaded from the official CDN, not a local copy, not a pinned hash from 2023.
5. No `console.log`, `console.warn`, `console.error` calls remain in component.js or inline script blocks.
6. The component's outer container does not overflow the viewport on a 375px-wide mobile screen.
7. Text in the component is legible (minimum 12px computed font size, minimum contrast ratio 4.5:1 against background).
The auditor must simulate this check by reading the component code and tracing resource loads. If a headless render tool is available, it must be used.
---
## QUICK REFERENCE CARD
```
FONTS Inter Tight (display, body) | JetBrains Mono (mono, counters) [LOCKED]
Fraunces (cinematic headlines) | Crimson Pro (editorial body) [extended]
Space Grotesk (geometric sans alt) | DM Mono (secondary mono) [extended]
PRIMARY #635bff → hover #5851e6
GRADIENT linear-gradient(135deg,#7a73ff 0%,#635bff 35%,#4f46e5 65%,#2563eb 100%)
ACCENTS #a8a3ff #b8b3ff #cdd2ff #4f7dff #2563eb
BACKGROUNDS #06081a #08091a #0a0c1e #0a0e1f
SURFACES #f4f5f8 #fafbfc #f7f8fa #fdfcfb
MID-TONES #1a1f36 #3c4257 #697386 #8792a2 #a4a9bd
ORB https://pub-86e919b2b9b945e7b0ce2253d77de22b.r2.dev/apex-logo-256.png
EMAIL info@apexopsystem.com (singular, no trailing s)
WEBSITE apexopsystems.com (plural, WITH trailing s)
FORBIDDEN COLORS red, green, amber, orange, yellow, magenta, pink, fuchsia, rose, salmon, coral
FORBIDDEN CHARS em-dash U+2014, en-dash U+2013, smart quotes, any emoji
FORBIDDEN CSS animated filter:blur, animated backdrop-filter, persistent filter:blur
FORBIDDEN PATTERNS magic numbers uncommented, setInterval without clearInterval, addEventListener without cleanup
REQUIRED GSAP autoAlpha (not opacity), force3D:true on transforms
REQUIRED CSS will-change:transform on animated layers
REQUIRED BOOT ScrollTrigger.normalizeScroll(true), gsap.ticker.lagSmoothing(500,33)
PARTICLE CAP 80 maximum simultaneous
CONSOLE MANDATE ZERO errors, ZERO warnings, ZERO deprecations in Chrome 120+
```
---
## AMENDMENT PROTOCOL
This file may only be amended by Ben (explicitly, in writing). The amendment process:
1. Ben states the change he wants to make.
2. The change is written into this document.
3. The document is committed to GitHub with message: `constitution: amend — [ben-approved]`
4. All active workers are notified of the updated constitution before their next job.
No AI worker, no developer, and no automated process may amend this file without Ben's explicit written instruction in the session where the amendment is committed. "Implicit approval" and "it seemed like Ben would want this" are not valid authorization.
---
*Apex Motion Engine Constitutional Specification. Locked 2026-05-30. Authored by agent A1 under Ben's direction. This file is the final word on every design and code decision in the Apex Motion Engine ecosystem.*
---
## SECTION 11 — AGENT ORCHESTRATION LAWS (ADDED 2026-05-30)
These laws govern HOW the Motion Engine factory runs Sonnet/Haiku/Claude agents. They are as inviolable as the brand laws above. Every conductor session reads them. Every agent prompt cites them.
### LAW A — 5-MINUTE MAX PER AGENT
No single agent runs longer than 5 minutes wall-clock. EVER.
If a task can take more than 5 min, SPLIT IT across N parallel agents:
- 4 components = 4 agents (one per component)
- 14 test samples = 7 agents (one per rule pair)
- 12 element-animation pairings = 12 agents
- 21 library cards to tag = 7 agents (3 cards each)
Rule of thumb: any work unit that takes more than 2 min of single-agent thinking gets its own agent.
WHY: 20 parallel 5-min agents = full system in 5 min wall-clock. 1 sequential 60-min agent = same work in 60 min wall-clock. The conductor's job is to PARALLELIZE, not to delegate big batches.
### LAW B — SWEEPS SPLIT BY FILE COUNT
Any audit / sweep / scan / refactor that touches MORE THAN 3 FILES must be split across N parallel agents. Never serial. Never single-agent for repo-wide passes.
Pattern:
1. Conductor enumerates target files (find / ls)
2. Buckets them into N groups of 2-3
3. Fires N agents in parallel, each with a different bucket
4. One merger agent consolidates findings + applies cross-file fixes
5. Final auditor verifies the merged result
### LAW C — GIT ISOLATION (per-agent worktrees)
No two concurrent agents share the same git working directory or index. Period.
WHY: 20+ agents on a shared working tree cause `index.lock` contention, branch-switch collisions, partial commits, and merge conflicts that turn 3-min jobs into 15-min jobs. This was the root cause of the H-wave runtime explosion on 2026-05-30.
PATTERN (preferred):
- Conductor creates per-agent worktrees: `git worktree add /tmp/apex-w- -b `
- Each agent does ALL its work inside its worktree (no fights for git lock)
- Each agent commits + pushes its own branch
- Conductor merges branches via GitHub UI or scripted merge at the end
- `git worktree remove` once branch is merged
ALTERNATIVE (lighter):
- Pre-create one branch per agent BEFORE firing — each agent only writes its own files in its own folder
- File-locking sentinel pattern: each agent waits up to 30s for a `flock()`, gives up if not acquired
ESCAPE HATCH:
- If isolation fails mid-flight, use git plumbing (`hash-object` + `mktree` + `commit-tree` + `update-ref`) to bypass the shared index. Agents H4 + H5 used this on 2026-05-30 to recover.
LAW A + LAW B + LAW C are inseparable. Without isolation, the 5-min law is unenforceable because git serializes commits.
### LAW D — AUDITORS RUN PARALLEL TO BUILDERS
Auditors fire alongside builders, not after. Wait pattern (e.g. `sleep 120`) goes inside the auditor's own script so the conductor doesn't block. Auditors catch contract mismatches the builder's grep-based self-audit cannot see (proven by D1/D2/D4 catching 6 critical bugs the builders all reported "all-pass" on).
### LAW E — REPORT BACK MUST PROVE WORK
Every agent's final report MUST include:
- Output file paths (absolute)
- Git commit hash + branch name + push confirmation
- Audit results with literal grep/curl/md5 output (not "all pass" claims)
- Time elapsed
Grep-PASSed audits are NOT proof. CURL-RENDERED-OUTPUT is proof. MD5-MATCHED is proof. WALL-CLOCK-UNDER-5-MIN is proof.
### LAW F — IDLE CONDUCTOR = WASTED AGENTS
If the conductor has fewer than 10 concurrent agents in flight while there is open work in the build order, the conductor is failing. There is always work that can fire in parallel — library expansion, smoke tests, audits, integration glue, doc updates, deployments, refactors. Idleness = inefficiency.
### THESE LAWS APPLY TO EVERY FUTURE MOTION ENGINE SESSION
Reading APEX-MOTION-ENGINE-VISION.md and DO-NOT-CHANGE-EVER.md is mandatory pre-flight for every agent. Every agent prompt should include the relevant law text inline so the agent itself cites it back in their plan.
```
### Email Address (SINGULAR domain, NO trailing S)
```
info@apexopsystem.com
```
Every component, every template, every generated page that includes contact information uses exactly this string. Never `info@apexopsystems.com`, never `hello@`, never any other alias unless Ben explicitly adds it to this document.
### Website URL (PLURAL domain, WITH trailing S)
```
apexopsystems.com
```
Every external-facing URL, every footer copyright link, every "visit" reference uses exactly this domain. Never `apexopsystem.com` (that is the email domain, not the website domain). The distinction is intentional and permanent.
| String | Value |
|---|---|
| Contact email | `info@apexopsystem.com` (singular — no trailing s) |
| Website | `apexopsystems.com` (plural — with trailing s) |
| Full site URL | `https://apexopsystems.com` |
---
## SECTION 4 — FORBIDDEN (REJECTION ON SIGHT)
If any of the following appear in a generated component, the component FAILS the audit immediately. No exceptions. No partial credit. Fix and resubmit.
### 4.1 — Forbidden Colors
The following colors and any hex, rgb, hsl, named CSS value, or Tailwind class that maps to them are forbidden in all rendered output:
| Forbidden | Examples of what is also forbidden |
|---|---|
| Red | `#ff0000`, `#ef4444`, `#dc2626`, `#f87171`, `red`, `crimson`, `tomato` |
| Green | `#22c55e`, `#16a34a`, `#4ade80`, `green`, `emerald`, `lime`, `teal` (warm teal) |
| Amber | `#f59e0b`, `#d97706`, `amber`, `yellow-500`, `orange-400` |
| Orange | `#f97316`, `#ea580c`, `orange`, `tangerine` |
| Yellow | `#eab308`, `#fbbf24`, `yellow`, `gold` |
| Magenta | `#ec4899`, `#db2777`, `magenta`, `fuchsia` |
| Pink | `#f472b6`, `#fb7185`, `pink`, `hot pink` |
| Rose | `#fb7185`, `#f43f5e`, `rose` |
| Salmon / Peach / Coral | any hex value with dominant red+orange channel |
Status indicators specifically: use these substitutes.
- Success / passing / active: `--apex-primary` (#635bff) or `--accent-lilac` (#a8a3ff)
- Error / failing / stuck: `--mid-slate` (#3c4257) or a grey-muted treatment
- Warning / caution: `--accent-pale` (#cdd2ff) or dim the primary
- Live / recording state: a brighter purple pulse using `--apex-primary` at elevated opacity
### 4.2 — Forbidden Typography Characters
| Character | Unicode | Why |
|---|---|---|
| Em-dash | U+2014 (--) | Looks AI-generated. Never in any user-facing copy. Use a comma, period, or sentence break instead. |
| En-dash | U+2013 (-) | Same rule. Never in copy. Use a hyphen in ranges (e.g., "5-10") only if unavoidable. |
| Smart / curly quotes | U+2018 U+2019 U+201C U+201D | Let the browser handle typographic quotes. Never hardcode these in copy strings. |
| Emoji of any kind | Various | No emoji anywhere in user-facing copy, labels, headings, buttons, or status text. Use SVG icons exclusively. |
### 4.3 — Forbidden CSS/Animation Techniques
| Technique | Why It Is Banned |
|---|---|
| `filter: blur(...)` animated (in a `@keyframes`, GSAP tween, or transition) | Forces a new stacking context every frame. Destroys compositing. Paint killer on mobile. Causes jank at any scroll speed. |
| `backdrop-filter` animated (any property change in an animation or transition) | Same reason as above. Constant repaint of everything behind the element. |
| `filter: blur(...)` in persistent CSS at all | Pre-blurred radial gradient overlays (`background: radial-gradient(...)`) are fine. A CSS rule that applies `filter: blur` to a DOM element that stays in the DOM is not. If you need a blurry background shape, render it as a gradient or a pre-blurred PNG asset. |
| `transition: all` on any animated element | Catches unintended properties. Always specify the exact property: `transition: transform 0.3s ease, opacity 0.3s ease`. |
| `position: fixed` inside a `transform`ed ancestor | Breaks fixed positioning. GSAP ScrollTrigger pinning uses transforms. Never put fixed children inside pinned containers. |
### 4.4 — Forbidden Code Patterns
| Pattern | Why | Fix |
|---|---|---|
| Hardcoded magic numbers without an explanation comment | Impossible for the next worker to know what `1440`, `0.72`, or `3200` means | Add: `/* 1440px = max-width design breakpoint */` |
| `setInterval(fn, n)` without a stored reference and `clearInterval` call | Leaks timers. Accumulates on navigation or component unmount. Kills mobile performance over time. | `const timer = setInterval(fn, n); /* cleanup: clearInterval(timer) in destroy() */` |
| `addEventListener` without a documented cleanup path | Leaks event listeners. Accumulates on repeated component init. | Document the corresponding `removeEventListener` call in the component's `destroy()` or `cleanup()` function. |
| Inline `style=""` with pixel values for layout (except GSAP transforms) | Hard to audit, hard to override, hard to theme. | Use CSS custom properties and class names. Only exception: GSAP-set transform values (`style="transform: ..."`) which are controlled programmatically. |
| `console.log`, `console.warn`, `console.error` calls in shipped code | Every shipped component must render console-clean. | Remove all debug logs before submitting for audit. |
---
## SECTION 5 — REQUIRED TECHNIQUES
Every component that uses GSAP animation MUST implement the following patterns. No exceptions.
### 5.1 — GSAP Opacity: Use `autoAlpha`, Not `opacity`
```javascript
// WRONG — leaves display:block on invisible elements, breaks tab order and hit-testing
gsap.to(element, { opacity: 0 });
// CORRECT — sets both opacity:0 AND visibility:hidden, removes from interaction tree
gsap.to(element, { autoAlpha: 0 });
gsap.from(element, { autoAlpha: 0 }); // also correct for entrances
```
Use `autoAlpha` on all containers, overlays, panels, and any element that fully appears or disappears. Use plain `opacity` only when you intentionally want the element to remain in the interaction tree at zero opacity.
### 5.2 — GPU Compositing: `force3D: true` on Transform-Heavy Tweens
```javascript
// Required on any tween using x, y, scale, rotation, or skew on a significant element
gsap.to(element, {
x: 200,
y: -50,
scale: 1.2,
force3D: true, /* <-- promotes to GPU compositor layer for the duration of the tween */
duration: 0.6,
ease: 'power3.out'
});
```
Apply `force3D: true` to any tween on a card, hero element, particle, or any element that moves during scroll. This is required, not optional.
### 5.3 — CSS Layer Promotion: `will-change: transform`
```css
/* Apply to any CSS layer that will be animated by GSAP or CSS transitions */
.animated-card,
.scroll-panel,
.particle-layer,
.hero-headline,
.counter-display {
will-change: transform; /* Promotes to compositor layer pre-emptively */
}
/* Remove will-change after animation completes if the element will be static for > 2s */
/* GSAP autoRemoveChildren handles this for timelines */
```
### 5.4 — Scroll Normalization (required for all scroll-driven pages)
```javascript
// Must appear in the boot/init function of any page using ScrollTrigger
ScrollTrigger.normalizeScroll(true);
/* Normalizes scroll behavior across iOS rubber-band, touch devices, and desktop.
Prevents jank on mobile ScrollTrigger sequences. */
```
### 5.5 — Lag Smoothing (required for all pages using GSAP ticker)
```javascript
// Must appear at boot, before any ScrollTrigger or animation is registered
gsap.ticker.lagSmoothing(500, 33);
/* First arg: max ms lag before smoothing kicks in (500ms = half a second).
Second arg: adjusted delta cap in ms (33ms = ~30fps floor).
Prevents the "catch-up avalanche" after a browser tab goes inactive. */
```
### 5.6 — Particle Cap
```
Maximum simultaneous particles in any single scene: 80
```
This is a hard ceiling. Not a guideline. Not "80 unless it looks cool." 80. Above 80 simultaneous particles, mobile CPUs fall below 30fps. If a scene concept requires more visual density, achieve it with pre-rendered CSS gradients, SVG overlays, or layered blur-free backgrounds -- not live DOM particles.
---
## SECTION 6 — STRUCTURAL RULES
### 6.1 — File Structure: Every Component Ships These 5 Files
No component is considered complete until all 5 files exist and are committed.
```