TDvorak/SEEN
1
0
Fork 0
mirror of https://github.com/Dvorinka/SEEN.git synced 2026-06-03 20:13:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

small fix, don't worry about it

Browse Source
This commit is contained in:
Tomas Dvorak
2026-04-10 12:06:24 +02:00
commit 5c500a72b0
243 changed files with 44176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.blackbox/skills/develop-web-game/LICENSE.txt
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf of
any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don\'t include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.blackbox/skills/develop-web-game/SKILL.md
+149
View File
@@ -0,0 +1,149 @@
---
name: "develop-web-game"
description: "Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with render_game_to_text."
---
# Develop Web Game
Build games in small steps and validate every change. Treat each iteration as: implement → act → pause → observe → adjust.
## Skill paths (set once)
```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export WEB_GAME_CLIENT="$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js"
export WEB_GAME_ACTIONS="$CODEX_HOME/skills/develop-web-game/references/action_payloads.json"
```
User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
## Workflow
1. **Pick a goal.** Define a single feature or behavior to implement.
2. **Implement small.** Make the smallest change that moves the game forward.
3. **Ensure integration points.** Provide a single canvas and `window.render_game_to_text` so the test loop can read state.
4. **Add `window.advanceTime(ms)`.** Strongly prefer a deterministic step hook so the Playwright script can advance frames reliably; without it, automated tests can be flaky.
5. **Initialize progress.md.** If `progress.md` exists, read it first and confirm the original user prompt is recorded at the top (prefix with `Original prompt:`). Also note any TODOs and suggestions left by the previous agent. If missing, create it and write `Original prompt: <prompt>` at the top before appending updates.
6. **Verify Playwright availability.** Ensure `playwright` is available (local dependency or global install). If unsure, check `npx` first.
7. **Run the Playwright test script.** You must run `$WEB_GAME_CLIENT` after each meaningful change; do not invent a new client unless required.
8. **Use the payload reference.** Base actions on `$WEB_GAME_ACTIONS` to avoid guessing keys.
9. **Inspect state.** Capture screenshots and text state after each burst.
10. **Inspect screenshots.** Open the latest screenshot, verify expected visuals, fix any issues, and rerun the script. Repeat until correct.
11. **Verify controls and state (multi-step focus).** Exhaustively exercise all important interactions. For each, think through the full multi-step sequence it implies (cause → intermediate states → outcome) and verify the entire chain works end-to-end. Confirm `render_game_to_text` reflects the same state shown on screen. If anything is off, fix and rerun.
Examples of important interactions: move, jump, shoot/attack, interact/use, select/confirm/cancel in menus, pause/resume, restart, and any special abilities or puzzle actions defined by the request. Multi-step examples: shooting an enemy should reduce its health; when health reaches 0 it should disappear and update the score; collecting a key should unlock a door and allow level progression.
12. **Check errors.** Review console errors and fix the first new issue before continuing.
13. **Reset between scenarios.** Avoid cross-test state when validating distinct features.
14. **Iterate with small deltas.** Change one variable at a time (frames, inputs, timing, positions), then repeat steps 7–13 until stable.
Example command (actions required):
```
node "$WEB_GAME_CLIENT" --url http://localhost:5173 --actions-file "$WEB_GAME_ACTIONS" --click-selector "#start-btn" --iterations 3 --pause-ms 250
```
Example actions (inline JSON):
```json
{
"steps": [
{ "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 120, "mouse_y": 80 },
{ "buttons": [], "frames": 6 },
{ "buttons": ["right"], "frames": 8 },
{ "buttons": ["space"], "frames": 4 }
]
}
```
## Test Checklist
Test any new features added for the request and any areas your logic changes could affect. Identify issues, fix them, and re-run the tests to confirm they’re resolved.
Examples of things to test:
- Primary movement/interaction inputs (e.g., move, jump, shoot, confirm/select).
- Win/lose or success/fail transitions.
- Score/health/resource changes.
- Boundary conditions (collisions, walls, screen edges).
- Menu/pause/start flow if present.
- Any special actions tied to the request (powerups, combos, abilities, puzzles, timers).
## Test Artifacts to Review
- Latest screenshots from the Playwright run.
- Latest `render_game_to_text` JSON output.
- Console error logs (fix the first new error before continuing).
You must actually open and visually inspect the latest screenshots after running the Playwright script, not just generate them. Ensure everything that should be visible on screen is actually visible. Go beyond the start screen and capture gameplay screenshots that cover all newly added features. Treat the screenshots as the source of truth; if something is missing, it is missing in the build. If you suspect a headless/WebGL capture issue, rerun the Playwright script in headed mode and re-check. Fix and rerun in a tight loop until the screenshots and text state look correct. Once fixes are verified, re-test all important interactions and controls, confirm they work, and ensure your changes did not introduce regressions. If they did, fix them and rerun everything in a loop until interactions, text state, and controls all work as expected. Be exhaustive in testing controls; broken games are not acceptable.
## Core Game Guidelines
### Canvas + Layout
- Prefer a single canvas centered in the window.
### Visuals
- Keep on-screen text minimal; show controls on a start/menu screen rather than overlaying them during play.
- Avoid overly dark scenes unless the design calls for it. Make key elements easy to see.
- Draw the background on the canvas itself instead of relying on CSS backgrounds.
### Text State Output (render_game_to_text)
Expose a `window.render_game_to_text` function that returns a concise JSON string representing the current game state. The text should include enough information to play the game without visuals.
Minimal pattern:
```js
function renderGameToText() {
const payload = {
mode: state.mode,
player: { x: state.player.x, y: state.player.y, r: state.player.r },
entities: state.entities.map((e) => ({ x: e.x, y: e.y, r: e.r })),
score: state.score,
};
return JSON.stringify(payload);
}
window.render_game_to_text = renderGameToText;
```
Keep the payload succinct and biased toward on-screen/interactive elements. Prefer current, visible entities over full history.
Include a clear coordinate system note (origin and axis directions), and encode all player-relevant state: player position/velocity, active obstacles/enemies, collectibles, timers/cooldowns, score, and any mode/state flags needed to make correct decisions. Avoid large histories; only include what's currently relevant and visible.
### Time Stepping Hook
Provide a deterministic time-stepping hook so the Playwright client can advance the game in controlled increments. Expose `window.advanceTime(ms)` (or a thin wrapper that forwards to your game update loop) and have the game loop use it when present.
The Playwright test script uses this hook to step frames deterministically during automated testing.
Minimal pattern:
```js
window.advanceTime = (ms) => {
const steps = Math.max(1, Math.round(ms / (1000 / 60)));
for (let i = 0; i < steps; i++) update(1 / 60);
render();
};
```
### Fullscreen Toggle
- Use a single key (prefer `f`) to toggle fullscreen on/off.
- Allow `Esc` to exit fullscreen.
- When fullscreen toggles, resize the canvas/rendering so visuals and input mapping stay correct.
## Progress Tracking
Create a `progress.md` file if it doesn't exist, and append TODOs, notes, gotchas, and loose ends as you go so another agent can pick up seamlessly.
If a `progress.md` file already exists, read it first, including the original user prompt at the top (you may be continuing another agent's work). Do not overwrite the original prompt; preserve it.
Update `progress.md` after each meaningful chunk of work (feature added, bug found, test run, or decision made).
At the end of your work, leave TODOs and suggestions for the next agent in `progress.md`.
## Playwright Prerequisites
- Prefer a local `playwright` dependency if the project already has it.
- If unsure whether Playwright is available, check for `npx`:
```
command -v npx >/dev/null 2>&1
```
- If `npx` is missing, install Node/npm and then install Playwright globally:
```
npm install -g @playwright/mcp@latest
```
- Do not switch to `@playwright/test` unless explicitly asked; stick to the client script.
## Scripts
- `$WEB_GAME_CLIENT` (installed default: `$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js`) — Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. You must pass an action burst via `--actions-file`, `--actions-json`, or `--click`.
## References
- `$WEB_GAME_ACTIONS` (installed default: `$CODEX_HOME/skills/develop-web-game/references/action_payloads.json`) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.
.blackbox/skills/develop-web-game/agents/openai.yaml
+6
View File
@@ -0,0 +1,6 @@
interface:
display_name: "Develop Web Game"
short_description: "Web game dev + Playwright test loop"
icon_small: "./assets/game-small.svg"
icon_large: "./assets/game.png"
default_prompt: "Build and iterate a playable web game in this workspace, validating changes with a Playwright loop."
.blackbox/skills/develop-web-game/assets/game-small.svg
+4
View File
@@ -0,0 +1,4 @@
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
<path fill="currentColor" d="M13.976 9.519a1.052 1.052 0 0 1 .901.52c.094.16.141.333.141.52 0 .188-.047.362-.14.522a1.054 1.054 0 0 1-.902.52c-.187 0-.36-.046-.52-.14a1.051 1.051 0 0 1-.522-.901 1.05 1.05 0 0 1 1.042-1.041ZM6.367 6.227c.229 0 .428.084.595.25.159.16.239.355.239.584v.833h.833c.229 0 .423.083.583.25a.78.78 0 0 1 .25.584.813.813 0 0 1-.25.593.795.795 0 0 1-.583.24H7.2v.833c0 .229-.08.428-.24.594a.831.831 0 0 1-.594.24.795.795 0 0 1-.583-.24.814.814 0 0 1-.25-.594V9.56H4.7a.832.832 0 0 1-.595-.24.83.83 0 0 1-.24-.593c0-.23.08-.425.24-.584a.813.813 0 0 1 .595-.25h.833V7.06c0-.23.083-.424.25-.583a.778.778 0 0 1 .583-.251Zm5.868 1.459a1.053 1.053 0 0 1 .901.52c.094.16.141.333.141.52 0 .188-.047.362-.14.522a1.054 1.054 0 0 1-.902.52c-.187 0-.36-.046-.52-.14a1.051 1.051 0 0 1-.522-.901 1.05 1.05 0 0 1 1.042-1.041Zm3.335 0c.186 0 .36.047.52.14a1.051 1.051 0 0 1 .52.9c0 .188-.047.362-.14.522a1.053 1.053 0 0 1-.9.52c-.188 0-.363-.046-.522-.14a1.051 1.051 0 0 1-.52-.901c0-.188.046-.361.14-.521a1.051 1.051 0 0 1 .901-.52Zm-1.594-1.833a1.053 1.053 0 0 1 .901.52c.094.16.141.333.141.52 0 .188-.047.362-.14.522a1.054 1.054 0 0 1-.902.52c-.187 0-.36-.046-.52-.14a1.051 1.051 0 0 1-.522-.901 1.05 1.05 0 0 1 1.042-1.041Z"/>
<path fill="currentColor" fill-rule="evenodd" d="M13.594 2.583c1.354 0 2.527.367 3.448 1.161.927.793 1.47 1.9 1.678 3.245l.844 5.448c.14.896.083 1.74-.205 2.507l.001.001a3.664 3.664 0 0 1-1.435 1.836l-.006.004c-.677.44-1.467.642-2.336.642-.65 0-1.249-.093-1.772-.306a3.31 3.31 0 0 1-1.357-1.03c-.357-.45-.648-1.02-.888-1.679l-.002-.004-.264-.742H8.7l-.265.742-.002.004c-.24.66-.53 1.229-.887 1.679a3.31 3.31 0 0 1-1.358 1.03c-.524.213-1.126.306-1.782.306-.866 0-1.654-.198-2.33-.628l-.004-.002A3.638 3.638 0 0 1 .634 15.01l-.003-.007c-.283-.753-.34-1.582-.206-2.46v-.001L1.28 6.99c.209-1.343.748-2.452 1.668-3.246l.003-.002c.927-.792 2.101-1.159 3.456-1.159h7.188Zm-7.188 1.5c-1.076 0-1.88.286-2.481.8-.593.512-.997 1.264-1.164 2.336l-.853 5.55c-.102.674-.049 1.233.125 1.7l.072.17c.18.384.439.675.777.894l.152.09c.368.194.817.304 1.372.304.524 0 .922-.074 1.218-.195.282-.114.53-.3.746-.573.226-.285.448-.695.652-1.256l.313-.875.008-.02c.07-.18.182-.39.374-.556.248-.223.547-.286.794-.286h2.978c.236 0 .519.059.76.259l.034.027c.192.166.304.377.374.557l.008.02.312.874c.204.56.427.971.653 1.256.216.273.464.458.746.573.296.12.691.195 1.207.195.628 0 1.121-.144 1.513-.398.396-.262.68-.62.856-1.1l.003-.007c.181-.48.236-1.057.127-1.754l-.844-5.45c-.166-1.07-.574-1.823-1.174-2.335l-.002-.003c-.593-.511-1.393-.797-2.469-.797H6.407Z" clip-rule="evenodd"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

.blackbox/skills/develop-web-game/assets/game.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.2 KiB

.blackbox/skills/develop-web-game/references/action_payloads.json
+7
View File
@@ -0,0 +1,7 @@
{
"steps": [
{ "buttons": ["left"], "frames": 6 },
{ "buttons": [], "frames": 4 },
{ "buttons": ["space"], "frames": 3 }
]
}
.blackbox/skills/develop-web-game/scripts/web_game_playwright_client.js
+356
View File
@@ -0,0 +1,356 @@
import fs from "node:fs";
import path from "node:path";
import { chromium } from "playwright";
function parseArgs(argv) {
const args = {
url: null,
iterations: 3,
pauseMs: 250,
headless: true,
screenshotDir: "output/web-game",
actionsFile: null,
actionsJson: null,
click: null,
clickSelector: null,
};
for (let i = 2; i < argv.length; i++) {
const arg = argv[i];
const next = argv[i + 1];
if (arg === "--url" && next) {
args.url = next;
i++;
} else if (arg === "--iterations" && next) {
args.iterations = parseInt(next, 10);
i++;
} else if (arg === "--pause-ms" && next) {
args.pauseMs = parseInt(next, 10);
i++;
} else if (arg === "--headless" && next) {
args.headless = next !== "0" && next !== "false";
i++;
} else if (arg === "--screenshot-dir" && next) {
args.screenshotDir = next;
i++;
} else if (arg === "--actions-file" && next) {
args.actionsFile = next;
i++;
} else if (arg === "--actions-json" && next) {
args.actionsJson = next;
i++;
} else if (arg === "--click" && next) {
const parts = next.split(",").map((v) => parseFloat(v.trim()));
if (parts.length === 2 && parts.every((v) => Number.isFinite(v))) {
args.click = { x: parts[0], y: parts[1] };
}
i++;
} else if (arg === "--click-selector" && next) {
args.clickSelector = next;
i++;
}
}
if (!args.url) {
throw new Error("--url is required");
}
return args;
}
const buttonNameToKey = {
up: "ArrowUp",
down: "ArrowDown",
left: "ArrowLeft",
right: "ArrowRight",
enter: "Enter",
space: "Space",
a: "KeyA",
b: "KeyB",
};
async function sleep(ms) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
function ensureDir(p) {
fs.mkdirSync(p, { recursive: true });
}
function makeVirtualTimeShim() {
return `(() => {
const pending = new Set();
const origSetTimeout = window.setTimeout.bind(window);
const origSetInterval = window.setInterval.bind(window);
const origRequestAnimationFrame = window.requestAnimationFrame.bind(window);
window.__vt_pending = pending;
window.setTimeout = (fn, t, ...rest) => {
const task = {};
pending.add(task);
return origSetTimeout(() => {
pending.delete(task);
fn(...rest);
}, t);
};
window.setInterval = (fn, t, ...rest) => {
const task = {};
pending.add(task);
return origSetInterval(() => {
fn(...rest);
}, t);
};
window.requestAnimationFrame = (fn) => {
const task = {};
pending.add(task);
return origRequestAnimationFrame((ts) => {
pending.delete(task);
fn(ts);
});
};
window.advanceTime = (ms) => {
return new Promise((resolve) => {
const start = performance.now();
function step(now) {
if (now - start >= ms) return resolve();
origRequestAnimationFrame(step);
}
origRequestAnimationFrame(step);
});
};
window.__drainVirtualTimePending = () => pending.size;
})();`;
}
async function getCanvasHandle(page) {
const handle = await page.evaluateHandle(() => {
let best = null;
let bestArea = 0;
for (const canvas of document.querySelectorAll("canvas")) {
const area = (canvas.width || canvas.clientWidth || 0) * (canvas.height || canvas.clientHeight || 0);
if (area > bestArea) {
bestArea = area;
best = canvas;
}
}
return best;
});
return handle.asElement();
}
async function captureCanvasPngBase64(canvas) {
return canvas.evaluate((c) => {
if (!c || typeof c.toDataURL !== "function") return "";
const data = c.toDataURL("image/png");
const idx = data.indexOf(",");
return idx === -1 ? "" : data.slice(idx + 1);
});
}
async function isCanvasTransparent(canvas) {
if (!canvas) return true;
return canvas.evaluate((c) => {
try {
const w = c.width || c.clientWidth || 0;
const h = c.height || c.clientHeight || 0;
if (!w || !h) return true;
const size = Math.max(1, Math.min(16, w, h));
const probe = document.createElement("canvas");
probe.width = size;
probe.height = size;
const ctx = probe.getContext("2d");
if (!ctx) return true;
ctx.drawImage(c, 0, 0, size, size);
const data = ctx.getImageData(0, 0, size, size).data;
for (let i = 3; i < data.length; i += 4) {
if (data[i] !== 0) return false;
}
return true;
} catch {
return false;
}
});
}
async function captureScreenshot(page, canvas, outPath) {
let buffer = null;
let base64 = canvas ? await captureCanvasPngBase64(canvas) : "";
if (base64) {
buffer = Buffer.from(base64, "base64");
const transparent = canvas ? await isCanvasTransparent(canvas) : false;
if (transparent) buffer = null;
}
if (!buffer && canvas) {
try {
buffer = await canvas.screenshot({ type: "png" });
} catch {
buffer = null;
}
}
if (!buffer) {
const bbox = canvas ? await canvas.boundingBox() : null;
if (bbox) {
buffer = await page.screenshot({
type: "png",
omitBackground: false,
clip: bbox,
});
} else {
buffer = await page.screenshot({ type: "png", omitBackground: false });
}
}
fs.writeFileSync(outPath, buffer);
}
class ConsoleErrorTracker {
constructor() {
this._seen = new Set();
this._errors = [];
}
ingest(err) {
const key = JSON.stringify(err);
if (this._seen.has(key)) return;
this._seen.add(key);
this._errors.push(err);
}
drain() {
const next = [...this._errors];
this._errors = [];
return next;
}
}
async function doChoreography(page, canvas, steps) {
for (const step of steps) {
const buttons = new Set(step.buttons || []);
for (const button of buttons) {
if (button === "left_mouse_button" || button === "right_mouse_button") {
const bbox = canvas ? await canvas.boundingBox() : null;
if (!bbox) continue;
const x = typeof step.mouse_x === "number" ? step.mouse_x : bbox.width / 2;
const y = typeof step.mouse_y === "number" ? step.mouse_y : bbox.height / 2;
await page.mouse.move(bbox.x + x, bbox.y + y);
await page.mouse.down({ button: button === "left_mouse_button" ? "left" : "right" });
} else if (buttonNameToKey[button]) {
await page.keyboard.down(buttonNameToKey[button]);
}
}
const frames = step.frames || 1;
for (let i = 0; i < frames; i++) {
await page.evaluate(async () => {
if (typeof window.advanceTime === "function") {
await window.advanceTime(1000 / 60);
}
});
}
for (const button of buttons) {
if (button === "left_mouse_button" || button === "right_mouse_button") {
await page.mouse.up({ button: button === "left_mouse_button" ? "left" : "right" });
} else if (buttonNameToKey[button]) {
await page.keyboard.up(buttonNameToKey[button]);
}
}
}
}
async function main() {
const args = parseArgs(process.argv);
ensureDir(args.screenshotDir);
const browser = await chromium.launch({
headless: args.headless,
args: ["--use-gl=angle", "--use-angle=swiftshader"],
});
const page = await browser.newPage();
const consoleErrors = new ConsoleErrorTracker();
page.on("console", (msg) => {
if (msg.type() !== "error") return;
consoleErrors.ingest({ type: "console.error", text: msg.text() });
});
page.on("pageerror", (err) => {
consoleErrors.ingest({ type: "pageerror", text: String(err) });
});
await page.addInitScript({ content: makeVirtualTimeShim() });
await page.goto(args.url, { waitUntil: "domcontentloaded" });
await page.waitForTimeout(500);
await page.evaluate(() => {
window.dispatchEvent(new Event("resize"));
});
let canvas = await getCanvasHandle(page);
if (args.clickSelector) {
try {
await page.click(args.clickSelector, { timeout: 5000 });
await page.waitForTimeout(250);
} catch (err) {
console.warn("Failed to click selector", args.clickSelector, err);
}
}
let steps = null;
if (args.actionsFile) {
const raw = fs.readFileSync(args.actionsFile, "utf-8");
const parsed = JSON.parse(raw);
if (Array.isArray(parsed)) steps = parsed;
if (parsed && Array.isArray(parsed.steps)) steps = parsed.steps;
} else if (args.actionsJson) {
const parsed = JSON.parse(args.actionsJson);
if (Array.isArray(parsed)) steps = parsed;
if (parsed && Array.isArray(parsed.steps)) steps = parsed.steps;
} else if (args.click) {
steps = [
{
buttons: ["left_mouse_button"],
frames: 2,
mouse_x: args.click.x,
mouse_y: args.click.y,
},
];
}
if (!steps) {
throw new Error("Actions are required. Use --actions-file, --actions-json, or --click.");
}
for (let i = 0; i < args.iterations; i++) {
if (!canvas) canvas = await getCanvasHandle(page);
await doChoreography(page, canvas, steps);
await sleep(args.pauseMs);
const shotPath = path.join(args.screenshotDir, `shot-${i}.png`);
await captureScreenshot(page, canvas, shotPath);
const text = await page.evaluate(() => {
if (typeof window.render_game_to_text === "function") {
return window.render_game_to_text();
}
return null;
});
if (text) {
fs.writeFileSync(path.join(args.screenshotDir, `state-${i}.json`), text);
}
const freshErrors = consoleErrors.drain();
if (freshErrors.length) {
fs.writeFileSync(
path.join(args.screenshotDir, `errors-${i}.json`),
JSON.stringify(freshErrors, null, 2)
);
break;
}
}
await browser.close();
}
main().catch((err) => {
console.error(err);
process.exit(1);
});
.blackbox/skills/frontend-design/SKILL.md
+68
View File
@@ -0,0 +1,68 @@
---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces for web components, pages, dashboards, admin panels, marketing sites, product UIs, and full web apps. Use when Codex needs to design or implement HTML/CSS/JS or React/Vue/Tailwind frontends, especially when the request calls for strong visual direction, polished interactions, responsiveness, or avoiding generic AI aesthetics.
---
# Frontend Design
## Workflow
1. Inspect the product context, existing code, design tokens, component library, and brand cues before changing the UI.
2. Preserve the established visual language when the project already has one. If the surface is greenfield, choose one clear aesthetic direction and state it briefly before coding.
3. Build real, working UI. Do not stop at mockup language or decorative shells when the request implies production code.
4. Refine spacing, hierarchy, states, responsiveness, and accessibility until the result feels deliberate.
5. Verify the result in a browser or preview when possible, and fix visible layout issues before finishing.
## Art Direction
- Pick one visual thesis and commit to it: editorial, brutalist, industrial, retro-futuristic, soft tactile, luxury, playful, or another context-fit direction.
- Make at least one memorable decision in typography, composition, motion, texture, or layout.
- Match the interface to the product and audience. Boldness is optional; intentionality is not.
- Avoid generic SaaS defaults, especially purple-on-white gradients, interchangeable card grids, and library-demo layouts.
## Typography
- Prefer distinctive fonts over default UI stacks unless the repo already standardizes them.
- Avoid Arial, Inter, Roboto, Open Sans, Lato, and system UI defaults for greenfield work.
- Good directions include IBM Plex Sans, Source Sans 3, Newsreader, Fraunces, Syne, Bricolage Grotesque, and JetBrains Mono.
- Use one or two font families. Let size, weight, and rhythm create hierarchy.
- Favor high-contrast display/body pairings when the product tone allows it.
## Color and Surface
- Define a compact set of tokens or CSS variables before styling heavily.
- Choose a dominant palette with clear accent and contrast roles.
- Build atmosphere with gradients, glows, textures, grids, patterns, or shadows that reinforce the concept.
- Create focal points. Do not distribute colors evenly across every element.
- Avoid startup-blue or purple-gradient defaults unless the brand already uses them.
## Layout and Motion
- Compose with rhythm. Use asymmetry, overlap, density shifts, grid breaks, or negative space when they improve the result.
- Use motion sparingly but intentionally: a strong page-load reveal, good hover/focus states, and transitions that support hierarchy are usually enough.
- Avoid noisy animation, random bouncing, and microinteraction clutter.
- Check desktop and mobile layouts explicitly. Fix overflow, cramped sections, and awkward line wrapping.
## Implementation Rules
- Respect the requested stack. If none is specified, choose the smallest practical implementation that fits the task.
- Reuse existing components, tokens, and conventions when working inside an established codebase.
- Prefer semantic HTML, accessible controls, visible focus states, and sensible reduced-motion behavior.
- Ship complete states where relevant: hover, focus, active, disabled, empty, loading, and error.
- Keep code production-minded. Extract reusable patterns when the interface is more than a one-off section.
## Frontend-Specific Heuristics
- For React or Vue, follow project conventions first and avoid abstraction that the codebase does not need.
- For self-contained HTML/CSS/JS requests, keep the output easy to run and easy to inspect.
- For Tailwind projects, avoid utility soup. Create a coherent token system and composition style.
- For dashboards and admin tools, prioritize information hierarchy and density control over decoration.
- For landing pages and marketing surfaces, make the first screen memorable through typography, composition, and a clear call to action.
## Definition of Done
- The UI has a clear aesthetic point of view.
- The result does not look template-generated.
- The implementation is responsive and functional.
- Visual polish is visible in spacing, typography, states, and motion.
- The design fits the actual product context rather than a generic demo.
.blackbox/skills/frontend-design/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "Frontend Design"
short_description: "Build distinctive production-grade frontends"
default_prompt: "Use $frontend-design to build a polished, distinctive frontend for this product."
.blackbox/skills/i-adapt/SKILL.md
+190
View File
@@ -0,0 +1,190 @@
---
name: i-adapt
description: Adapt designs to work across different screen sizes, devices, contexts, or platforms. Ensures consistent experience across varied environments.
---
Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases.
## Assess Adaptation Challenge
Understand what needs adaptation and why:
1. **Identify the source context**:
- What was it designed for originally? (Desktop web? Mobile app?)
- What assumptions were made? (Large screen? Mouse input? Fast connection?)
- What works well in current context?
2. **Understand target context**:
- **Device**: Mobile, tablet, desktop, TV, watch, print?
- **Input method**: Touch, mouse, keyboard, voice, gamepad?
- **Screen constraints**: Size, resolution, orientation?
- **Connection**: Fast wifi, slow 3G, offline?
- **Usage context**: On-the-go vs desk, quick glance vs focused reading?
- **User expectations**: What do users expect on this platform?
3. **Identify adaptation challenges**:
- What won't fit? (Content, navigation, features)
- What won't work? (Hover states on touch, tiny touch targets)
- What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context.
## Plan Adaptation Strategy
Create context-appropriate strategy:
### Mobile Adaptation (Desktop → Mobile)
**Layout Strategy**:
- Single column instead of multi-column
- Vertical stacking instead of side-by-side
- Full-width components instead of fixed widths
- Bottom navigation instead of top/side navigation
**Interaction Strategy**:
- Touch targets 44x44px minimum (not hover-dependent)
- Swipe gestures where appropriate (lists, carousels)
- Bottom sheets instead of dropdowns
- Thumbs-first design (controls within thumb reach)
- Larger tap areas with more spacing
**Content Strategy**:
- Progressive disclosure (don't show everything at once)
- Prioritize primary content (secondary content in tabs/accordions)
- Shorter text (more concise)
- Larger text (16px minimum)
**Navigation Strategy**:
- Hamburger menu or bottom navigation
- Reduce navigation complexity
- Sticky headers for context
- Back button in navigation flow
### Tablet Adaptation (Hybrid Approach)
**Layout Strategy**:
- Two-column layouts (not single or three-column)
- Side panels for secondary content
- Master-detail views (list + detail)
- Adaptive based on orientation (portrait vs landscape)
**Interaction Strategy**:
- Support both touch and pointer
- Touch targets 44x44px but allow denser layouts than phone
- Side navigation drawers
- Multi-column forms where appropriate
### Desktop Adaptation (Mobile → Desktop)
**Layout Strategy**:
- Multi-column layouts (use horizontal space)
- Side navigation always visible
- Multiple information panels simultaneously
- Fixed widths with max-width constraints (don't stretch to 4K)
**Interaction Strategy**:
- Hover states for additional information
- Keyboard shortcuts
- Right-click context menus
- Drag and drop where helpful
- Multi-select with Shift/Cmd
**Content Strategy**:
- Show more information upfront (less progressive disclosure)
- Data tables with many columns
- Richer visualizations
- More detailed descriptions
### Print Adaptation (Screen → Print)
**Layout Strategy**:
- Page breaks at logical points
- Remove navigation, footer, interactive elements
- Black and white (or limited color)
- Proper margins for binding
**Content Strategy**:
- Expand shortened content (show full URLs, hidden sections)
- Add page numbers, headers, footers
- Include metadata (print date, page title)
- Convert charts to print-friendly versions
### Email Adaptation (Web → Email)
**Layout Strategy**:
- Narrow width (600px max)
- Single column only
- Inline CSS (no external stylesheets)
- Table-based layouts (for email client compatibility)
**Interaction Strategy**:
- Large, obvious CTAs (buttons not text links)
- No hover states (not reliable)
- Deep links to web app for complex interactions
## Implement Adaptations
Apply changes systematically:
### Responsive Breakpoints
Choose appropriate breakpoints:
- Mobile: 320px-767px
- Tablet: 768px-1023px
- Desktop: 1024px+
- Or content-driven breakpoints (where design breaks)
### Layout Adaptation Techniques
- **CSS Grid/Flexbox**: Reflow layouts automatically
- **Container Queries**: Adapt based on container, not viewport
- **`clamp()`**: Fluid sizing between min and max
- **Media queries**: Different styles for different contexts
- **Display properties**: Show/hide elements per context
### Touch Adaptation
- Increase touch target sizes (44x44px minimum)
- Add more spacing between interactive elements
- Remove hover-dependent interactions
- Add touch feedback (ripples, highlights)
- Consider thumb zones (easier to reach bottom than top)
### Content Adaptation
- Use `display: none` sparingly (still downloads)
- Progressive enhancement (core content first, enhancements on larger screens)
- Lazy loading for off-screen content
- Responsive images (`srcset`, `picture` element)
### Navigation Adaptation
- Transform complex nav to hamburger/drawer on mobile
- Bottom nav bar for mobile apps
- Persistent side navigation on desktop
- Breadcrumbs on smaller screens for context
**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.
**NEVER**:
- Hide core functionality on mobile (if it matters, make it work)
- Assume desktop = powerful device (consider accessibility, older machines)
- Use different information architecture across contexts (confusing)
- Break user expectations for platform (mobile users expect mobile patterns)
- Forget landscape orientation on mobile/tablet
- Use generic breakpoints blindly (use content-driven breakpoints)
- Ignore touch on desktop (many desktop devices have touch)
## Verify Adaptations
Test thoroughly across contexts:
- **Real devices**: Test on actual phones, tablets, desktops
- **Different orientations**: Portrait and landscape
- **Different browsers**: Safari, Chrome, Firefox, Edge
- **Different OS**: iOS, Android, Windows, macOS
- **Different input methods**: Touch, mouse, keyboard
- **Edge cases**: Very small screens (320px), very large screens (4K)
- **Slow connections**: Test on throttled network
Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
.blackbox/skills/i-animate/SKILL.md
+185
View File
@@ -0,0 +1,185 @@
---
name: i-animate
description: Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight.
---
Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Animation Opportunities
Analyze where motion would improve the experience:
1. **Identify static areas**:
- **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
- **Jarring transitions**: Instant state changes that feel abrupt (show/hide, page loads, route changes)
- **Unclear relationships**: Spatial or hierarchical relationships that aren't obvious
- **Lack of delight**: Functional but joyless interactions
- **Missed guidance**: Opportunities to direct attention or explain behavior
2. **Understand the context**:
- What's the personality? (Playful vs serious, energetic vs calm)
- What's the performance budget? (Mobile-first? Complex page?)
- Who's the audience? (Motion-sensitive users? Power users who want speed?)
- What matters most? (One hero animation vs many micro-interactions?)
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
## Plan Animation Strategy
Create a purposeful animation plan:
- **Hero moment**: What's the ONE signature animation? (Page load? Hero section? Key interaction?)
- **Feedback layer**: Which interactions need acknowledgment?
- **Transition layer**: Which state changes need smoothing?
- **Delight layer**: Where can we surprise and delight?
**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.
## Implement Animations
Add motion systematically across these categories:
### Entrance Animations
- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
- **Content reveals**: Scroll-triggered animations using intersection observer
- **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
### Micro-interactions
- **Button feedback**:
- Hover: Subtle scale (1.02-1.05), color shift, shadow increase
- Click: Quick scale down then up (0.95 → 1), ripple effect
- Loading: Spinner or pulse state
- **Form interactions**:
- Input focus: Border color transition, slight scale or glow
- Validation: Shake on error, check mark on success, smooth color transitions
- **Toggle switches**: Smooth slide + color transition (200-300ms)
- **Checkboxes/radio**: Check mark animation, ripple effect
- **Like/favorite**: Scale + rotation, particle effects, color transition
### State Transitions
- **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms)
- **Expand/collapse**: Height transition with overflow handling, icon rotation
- **Loading states**: Skeleton screen fades, spinner animations, progress bars
- **Success/error**: Color transitions, icon animations, gentle scale pulse
- **Enable/disable**: Opacity transitions, cursor changes
### Navigation & Flow
- **Page transitions**: Crossfade between routes, shared element transitions
- **Tab switching**: Slide indicator, content fade/slide
- **Carousel/slider**: Smooth transforms, snap points, momentum
- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators
### Feedback & Guidance
- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
- **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning
- **Copy/paste**: Brief highlight flash on paste, "copied" confirmation
- **Focus flow**: Highlight path through form or workflow
### Delight Moments
- **Empty states**: Subtle floating animations on illustrations
- **Completed actions**: Confetti, check mark flourish, success celebrations
- **Easter eggs**: Hidden interactions for discovery
- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches
## Technical Implementation
Use appropriate techniques for each animation:
### Timing & Easing
**Durations by purpose:**
- **100-150ms**: Instant feedback (button press, toggle)
- **200-300ms**: State changes (hover, menu open)
- **300-500ms**: Layout changes (accordion, modal)
- **500-800ms**: Entrance animations (page load)
**Easing curves (use these, not CSS defaults):**
```css
/* Recommended - natural deceleration */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */
/* AVOID - feel dated and tacky */
/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
```
**Exit animations are faster than entrances.** Use ~75% of enter duration.
### CSS Animations
```css
/* Prefer for simple, declarative animations */
- transitions for state changes
- @keyframes for complex sequences
- transform + opacity only (GPU-accelerated)
```
### JavaScript Animation
```javascript
/* Use for complex, interactive animations */
- Web Animations API for programmatic control
- Framer Motion for React
- GSAP for complex sequences
```
### Performance
- **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties
- **will-change**: Add sparingly for known expensive animations
- **Reduce paint**: Minimize repaints, use `contain` where appropriate
- **Monitor FPS**: Ensure 60fps on target devices
### Accessibility
```css
@media (prefers-reduced-motion: reduce) {
* {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
```
**NEVER**:
- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself
- Animate layout properties (width, height, top, left)—use transform instead
- Use durations over 500ms for feedback—it feels laggy
- Animate without purpose—every animation needs a reason
- Ignore `prefers-reduced-motion`—this is an accessibility violation
- Animate everything—animation fatigue makes interfaces feel exhausting
- Block interaction during animations unless intentional
## Verify Quality
Test animations thoroughly:
- **Smooth at 60fps**: No jank on target devices
- **Feels natural**: Easing curves feel organic, not robotic
- **Appropriate timing**: Not too fast (jarring) or too slow (laggy)
- **Reduced motion works**: Animations disabled or simplified appropriately
- **Doesn't block**: Users can interact during/after animations
- **Adds value**: Makes interface clearer or more delightful
Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.
.blackbox/skills/i-audit/SKILL.md
+123
View File
@@ -0,0 +1,123 @@
---
name: i-audit
description: Perform comprehensive audit of interface quality across accessibility, performance, theming, and responsive design. Generates detailed report of issues with severity ratings and recommendations.
---
Run systematic quality checks and generate a comprehensive audit report with prioritized issues and actionable recommendations. Don't fix issues - document them for other commands to address.
**First**: Use the i-frontend-design skill for design principles and anti-patterns.
## Diagnostic Scan
Run comprehensive checks across multiple dimensions:
1. **Accessibility (A11y)** - Check for:
- **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA)
- **Missing ARIA**: Interactive elements without proper roles, labels, or states
- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps
- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons
- **Alt text**: Missing or poor image descriptions
- **Form issues**: Inputs without labels, poor error messaging, missing required indicators
2. **Performance** - Check for:
- **Layout thrashing**: Reading/writing layout properties in loops
- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
- **Bundle size**: Unnecessary imports, unused dependencies
- **Render performance**: Unnecessary re-renders, missing memoization
3. **Theming** - Check for:
- **Hard-coded colors**: Colors not using design tokens
- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme
- **Inconsistent tokens**: Using wrong tokens, mixing token types
- **Theme switching issues**: Values that don't update on theme change
4. **Responsive Design** - Check for:
- **Fixed widths**: Hard-coded widths that break on mobile
- **Touch targets**: Interactive elements < 44x44px
- **Horizontal scroll**: Content overflow on narrow viewports
- **Text scaling**: Layouts that break when text size increases
- **Missing breakpoints**: No mobile/tablet variants
5. **Anti-Patterns (CRITICAL)** - Check against ALL the **DON'T** guidelines in the i-frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
**CRITICAL**: This is an audit, not a fix. Document issues thoroughly with clear explanations of impact. Use other commands (normalize, optimize, harden, etc.) to fix issues after audit.
## Generate Comprehensive Report
Create a detailed audit report with the following structure:
### Anti-Patterns Verdict
**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest.
### Executive Summary
- Total issues found (count by severity)
- Most critical issues (top 3-5)
- Overall quality score (if applicable)
- Recommended next steps
### Detailed Findings by Severity
For each issue, document:
- **Location**: Where the issue occurs (component, file, line)
- **Severity**: Critical / High / Medium / Low
- **Category**: Accessibility / Performance / Theming / Responsive
- **Description**: What the issue is
- **Impact**: How it affects users
- **WCAG/Standard**: Which standard it violates (if applicable)
- **Recommendation**: How to fix it
- **Suggested command**: Which command to use (prefer: /i-quieter, /i-polish, /i-optimize, /i-onboard, /i-normalize, /i-harden, /i-extract, /i-distill, /i-delight, /i-critique, /i-colorize, /i-clarify, /i-bolder, /i-audit, /i-animate, /i-adapt — or other installed skills you're sure exist)
#### Critical Issues
[Issues that block core functionality or violate WCAG A]
#### High-Severity Issues
[Significant usability/accessibility impact, WCAG AA violations]
#### Medium-Severity Issues
[Quality issues, WCAG AAA violations, performance concerns]
#### Low-Severity Issues
[Minor inconsistencies, optimization opportunities]
### Patterns & Systemic Issues
Identify recurring problems:
- "Hard-coded colors appear in 15+ components, should use design tokens"
- "Touch targets consistently too small (<44px) throughout mobile experience"
- "Missing focus indicators on all custom interactive components"
### Positive Findings
Note what's working well:
- Good practices to maintain
- Exemplary implementations to replicate elsewhere
### Recommendations by Priority
Create actionable plan:
1. **Immediate**: Critical blockers to fix first
2. **Short-term**: High-severity issues (this sprint)
3. **Medium-term**: Quality improvements (next sprint)
4. **Long-term**: Nice-to-haves and optimizations
### Suggested Commands for Fixes
Map issues to available commands. Prefer these: /i-quieter, /i-polish, /i-optimize, /i-onboard, /i-normalize, /i-harden, /i-extract, /i-distill, /i-delight, /i-critique, /i-colorize, /i-clarify, /i-bolder, /i-audit, /i-animate, /i-adapt. You may also suggest other installed skills you're sure exist, but never invent commands.
Examples:
- "Use `/i-normalize` to align with design system (addresses N theming issues)"
- "Use `/i-optimize` to improve performance (addresses N performance issues)"
- "Use `/i-harden` to improve resilience (addresses N edge cases)"
**IMPORTANT**: Be thorough but actionable. Too many low-priority issues creates noise. Focus on what actually matters.
**NEVER**:
- Report issues without explaining impact (why does this matter?)
- Mix severity levels inconsistently
- Skip positive findings (celebrate what works)
- Provide generic recommendations (be specific and actionable)
- Forget to prioritize (everything can't be critical)
- Report false positives without verification
Remember: You're a quality auditor with exceptional attention to detail. Document systematically, prioritize ruthlessly, and provide clear paths to improvement. A good audit makes fixing easy.
.blackbox/skills/i-bolder/SKILL.md
+127
View File
@@ -0,0 +1,127 @@
---
name: i-bolder
description: Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability.
---
Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Guessing leads to generic AI slop.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Current State
Analyze what makes the design feel too safe or boring:
1. **Identify weakness sources**:
- **Generic choices**: System fonts, basic colors, standard layouts
- **Timid scale**: Everything is medium-sized with no drama
- **Low contrast**: Everything has similar visual weight
- **Static**: No motion, no energy, no life
- **Predictable**: Standard patterns with no surprises
- **Flat hierarchy**: Nothing stands out or commands attention
2. **Understand the context**:
- What's the brand personality? (How far can we push?)
- What's the purpose? (Marketing can be bolder than financial dashboards)
- Who's the audience? (What will resonate?)
- What are the constraints? (Brand guidelines, accessibility, performance)
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold—they're generic. Review ALL the DON'T guidelines in the i-frontend-design skill before proceeding. Bold means distinctive, not "more effects."
## Plan Amplification
Create a strategy to increase impact while maintaining coherence:
- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing)
- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
- **Risk budget**: How experimental can we be? Push boundaries within constraints.
- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast)
**IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
## Amplify the Design
Systematically increase impact across these dimensions:
### Typography Amplification
- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration)
- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x)
- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400
- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default)
### Color Intensification
- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
- **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop
- **Dominant color strategy**: Let one bold color own 60% of the design
- **Sharp accents**: High-contrast accent colors that pop
- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue)
### Spatial Drama
- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings
- **Break the grid**: Let hero elements escape containers and cross boundaries
- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry
- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px)
- **Overlap**: Layer elements intentionally for depth
### Visual Effects
- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
- **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop)
- **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
### Motion & Animation
- **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays
- **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences
- **Micro-interactions**: Satisfying hover effects, click feedback, state changes
- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect)
### Composition Boldness
- **Hero moments**: Create clear focal points with dramatic treatment
- **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements
- **Full-bleed elements**: Use full viewport width/height for impact
- **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits
**NEVER**:
- Add effects randomly without purpose (chaos ≠ bold)
- Sacrifice readability for aesthetics (body text must be readable)
- Make everything bold (then nothing is bold - need contrast)
- Ignore accessibility (bold design must still meet WCAG standards)
- Overwhelm with motion (animation fatigue is real)
- Copy trendy aesthetics blindly (bold means distinctive, not derivative)
## Verify Quality
Ensure amplification maintains usability and coherence:
- **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
- **Still functional**: Can users accomplish tasks without distraction?
- **Coherent**: Does everything feel intentional and unified?
- **Memorable**: Will users remember this experience?
- **Performant**: Do all these effects run smoothly?
- **Accessible**: Does it still meet accessibility standards?
**The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.
.blackbox/skills/i-clarify/SKILL.md
+174
View File
@@ -0,0 +1,174 @@
---
name: i-clarify
description: Improve unclear UX copy, error messages, microcopy, labels, and instructions. Makes interfaces easier to understand and use.
---
Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
## Assess Current Copy
Identify what makes the text unclear or ineffective:
1. **Find clarity problems**:
- **Jargon**: Technical terms users won't understand
- **Ambiguity**: Multiple interpretations possible
- **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
- **Length**: Too wordy or too terse
- **Assumptions**: Assuming user knowledge they don't have
- **Missing context**: Users don't know what to do or why
- **Tone mismatch**: Too formal, too casual, or inappropriate for situation
2. **Understand the context**:
- Who's the audience? (Technical? General? First-time users?)
- What's the user's mental state? (Stressed during error? Confident during success?)
- What's the action? (What do we want users to do?)
- What's the constraint? (Character limits? Space limitations?)
**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
## Plan Copy Improvements
Create a strategy for clearer communication:
- **Primary message**: What's the ONE thing users need to know?
- **Action needed**: What should users do next (if anything)?
- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
- **Constraints**: Length limits, brand voice, localization considerations
**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
## Improve Copy Systematically
Refine text across these common areas:
### Error Messages
**Bad**: "Error 403: Forbidden"
**Good**: "You don't have permission to view this page. Contact your admin for access."
**Bad**: "Invalid input"
**Good**: "Email addresses need an @ symbol. Try: name@example.com"
**Principles**:
- Explain what went wrong in plain language
- Suggest how to fix it
- Don't blame the user
- Include examples when helpful
- Link to help/support if applicable
### Form Labels & Instructions
**Bad**: "DOB (MM/DD/YYYY)"
**Good**: "Date of birth" (with placeholder showing format)
**Bad**: "Enter value here"
**Good**: "Your email address" or "Company name"
**Principles**:
- Use clear, specific labels (not generic placeholders)
- Show format expectations with examples
- Explain why you're asking (when not obvious)
- Put instructions before the field, not after
- Keep required field indicators clear
### Button & CTA Text
**Bad**: "Click here" | "Submit" | "OK"
**Good**: "Create account" | "Save changes" | "Got it, thanks"
**Principles**:
- Describe the action specifically
- Use active voice (verb + noun)
- Match user's mental model
- Be specific ("Save" is better than "OK")
### Help Text & Tooltips
**Bad**: "This is the username field"
**Good**: "Choose a username. You can change this later in Settings."
**Principles**:
- Add value (don't just repeat the label)
- Answer the implicit question ("What is this?" or "Why do you need this?")
- Keep it brief but complete
- Link to detailed docs if needed
### Empty States
**Bad**: "No items"
**Good**: "No projects yet. Create your first project to get started."
**Principles**:
- Explain why it's empty (if not obvious)
- Show next action clearly
- Make it welcoming, not dead-end
### Success Messages
**Bad**: "Success"
**Good**: "Settings saved! Your changes will take effect immediately."
**Principles**:
- Confirm what happened
- Explain what happens next (if relevant)
- Be brief but complete
- Match the user's emotional moment (celebrate big wins)
### Loading States
**Bad**: "Loading..." (for 30+ seconds)
**Good**: "Analyzing your data... this usually takes 30-60 seconds"
**Principles**:
- Set expectations (how long?)
- Explain what's happening (when it's not obvious)
- Show progress when possible
- Offer escape hatch if appropriate ("Cancel")
### Confirmation Dialogs
**Bad**: "Are you sure?"
**Good**: "Delete 'Project Alpha'? This can't be undone."
**Principles**:
- State the specific action
- Explain consequences (especially for destructive actions)
- Use clear button labels ("Delete project" not "Yes")
- Don't overuse confirmations (only for risky actions)
### Navigation & Wayfinding
**Bad**: Generic labels like "Items" | "Things" | "Stuff"
**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
**Principles**:
- Be specific and descriptive
- Use language users understand (not internal jargon)
- Make hierarchy clear
- Consider information scent (breadcrumbs, current location)
## Apply Clarity Principles
Every piece of copy should follow these rules:
1. **Be specific**: "Enter email" not "Enter value"
2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
3. **Be active**: "Save changes" not "Changes will be saved"
4. **Be human**: "Oops, something went wrong" not "System error encountered"
5. **Be helpful**: Tell users what to do, not just what happened
6. **Be consistent**: Use same terms throughout (don't vary for variety)
**NEVER**:
- Use jargon without explanation
- Blame users ("You made an error" → "This field is required")
- Be vague ("Something went wrong" without explanation)
- Use passive voice unnecessarily
- Write overly long explanations (be concise)
- Use humor for errors (be empathetic instead)
- Assume technical knowledge
- Vary terminology (pick one term and stick with it)
- Repeat information (headers restating intros, redundant explanations)
- Use placeholders as the only labels (they disappear when users type)
## Verify Improvements
Test that copy improvements work:
- **Comprehension**: Can users understand without context?
- **Actionability**: Do users know what to do next?
- **Brevity**: Is it as short as possible while remaining clear?
- **Consistency**: Does it match terminology elsewhere?
- **Tone**: Is it appropriate for the situation?
Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
.blackbox/skills/i-colorize/SKILL.md
+153
View File
@@ -0,0 +1,153 @@
---
name: i-colorize
description: Add strategic color to features that are too monochromatic or lack visual interest. Makes interfaces more engaging and expressive.
---
Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and especially existing brand colors.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Guessing leads to generic AI slop colors.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Color Opportunity
Analyze the current state and identify opportunities:
1. **Understand current state**:
- **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
- **Missed opportunities**: Where could color add meaning, hierarchy, or delight?
- **Context**: What's appropriate for this domain and audience?
- **Brand**: Are there existing brand colors we should use?
2. **Identify where color adds value**:
- **Semantic meaning**: Success (green), error (red), warning (yellow/orange), info (blue)
- **Hierarchy**: Drawing attention to important elements
- **Categorization**: Different sections, types, or states
- **Emotional tone**: Warmth, energy, trust, creativity
- **Wayfinding**: Helping users navigate and understand structure
- **Delight**: Moments of visual interest and personality
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
## Plan Color Strategy
Create a purposeful color introduction plan:
- **Color palette**: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals)
- **Dominant color**: Which color owns 60% of colored elements?
- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%)
- **Application strategy**: Where does each color appear and why?
**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.
## Introduce Color Strategically
Add color systematically across these dimensions:
### Semantic Color
- **State indicators**:
- Success: Green tones (emerald, forest, mint)
- Error: Red/pink tones (rose, crimson, coral)
- Warning: Orange/amber tones
- Info: Blue tones (sky, ocean, indigo)
- Neutral: Gray/slate for inactive states
- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.)
- **Progress indicators**: Colored bars, rings, or charts showing completion or health
### Accent Color Application
- **Primary actions**: Color the most important buttons/CTAs
- **Links**: Add color to clickable text (maintain accessibility)
- **Icons**: Colorize key icons for recognition and personality
- **Headers/titles**: Add color to section headers or key labels
- **Hover states**: Introduce color on interaction
### Background & Surfaces
- **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`)
- **Colored sections**: Use subtle background colors to separate areas
- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
- **Cards & surfaces**: Tint cards or surfaces slightly for warmth
**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales.
### Data Visualization
- **Charts & graphs**: Use color to encode categories or values
- **Heatmaps**: Color intensity shows density or importance
- **Comparison**: Color coding for different datasets or timeframes
### Borders & Accents
- **Accent borders**: Add colored left/top borders to cards or sections
- **Underlines**: Color underlines for emphasis or active states
- **Dividers**: Subtle colored dividers instead of gray lines
- **Focus rings**: Colored focus indicators matching brand
### Typography Color
- **Colored headings**: Use brand colors for section headings (maintain contrast)
- **Highlight text**: Color for emphasis or categories
- **Labels & tags**: Small colored labels for metadata or categories
### Decorative Elements
- **Illustrations**: Add colored illustrations or icons
- **Shapes**: Geometric shapes in brand colors as background elements
- **Gradients**: Colorful gradient overlays or mesh backgrounds
- **Blobs/organic shapes**: Soft colored shapes for visual interest
## Balance & Refinement
Ensure color addition improves rather than overwhelms:
### Maintain Hierarchy
- **Dominant color** (60%): Primary brand color or most used accent
- **Secondary color** (30%): Supporting color for variety
- **Accent color** (10%): High contrast for key moments
- **Neutrals** (remaining): Gray/black/white for structure
### Accessibility
- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
- **Don't rely on color alone**: Use icons, labels, or patterns alongside color
- **Test for color blindness**: Verify red/green combinations work for all users
### Cohesion
- **Consistent palette**: Use colors from defined palette, not arbitrary choices
- **Systematic application**: Same color meanings throughout (green always = success)
- **Temperature consistency**: Warm palette stays warm, cool stays cool
**NEVER**:
- Use every color in the rainbow (choose 2-4 colors beyond neutrals)
- Apply color randomly without semantic meaning
- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead
- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication
- Use pure black (`#000`) or pure white (`#fff`) for large areas
- Violate WCAG contrast requirements
- Use color as the only indicator (accessibility issue)
- Make everything colorful (defeats the purpose)
- Default to purple-blue gradients (AI slop aesthetic)
## Verify Color Addition
Test that colorization improves the experience:
- **Better hierarchy**: Does color guide attention appropriately?
- **Clearer meaning**: Does color help users understand states/categories?
- **More engaging**: Does the interface feel warmer and more inviting?
- **Still accessible**: Do all color combinations meet WCAG standards?
- **Not overwhelming**: Is color balanced and purposeful?
Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
.blackbox/skills/i-critique/SKILL.md
+113
View File
@@ -0,0 +1,113 @@
---
name: i-critique
description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback.
---
Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback.
**First**: Use the i-frontend-design skill for design principles and anti-patterns.
## Design Critique
Evaluate the interface across these dimensions:
### 1. AI Slop Detection (CRITICAL)
**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025?
Review the design against ALL the **DON'T** guidelines in the i-frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.
**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
### 2. Visual Hierarchy
- Does the eye flow to the most important element first?
- Is there a clear primary action? Can you spot it in 2 seconds?
- Do size, color, and position communicate importance correctly?
- Is there visual competition between elements that should have different weights?
### 3. Information Architecture
- Is the structure intuitive? Would a new user understand the organization?
- Is related content grouped logically?
- Are there too many choices at once? (cognitive overload)
- Is the navigation clear and predictable?
### 4. Emotional Resonance
- What emotion does this interface evoke? Is that intentional?
- Does it match the brand personality?
- Does it feel trustworthy, approachable, premium, playful—whatever it should feel?
- Would the target user feel "this is for me"?
### 5. Discoverability & Affordance
- Are interactive elements obviously interactive?
- Would a user know what to do without instructions?
- Are hover/focus states providing useful feedback?
- Are there hidden features that should be more visible?
### 6. Composition & Balance
- Does the layout feel balanced or uncomfortably weighted?
- Is whitespace used intentionally or just leftover?
- Is there visual rhythm in spacing and repetition?
- Does asymmetry feel designed or accidental?
### 7. Typography as Communication
- Does the type hierarchy clearly signal what to read first, second, third?
- Is body text comfortable to read? (line length, spacing, size)
- Do font choices reinforce the brand/tone?
- Is there enough contrast between heading levels?
### 8. Color with Purpose
- Is color used to communicate, not just decorate?
- Does the palette feel cohesive?
- Are accent colors drawing attention to the right things?
- Does it work for colorblind users? (not just technically—does meaning still come through?)
### 9. States & Edge Cases
- Empty states: Do they guide users toward action, or just say "nothing here"?
- Loading states: Do they reduce perceived wait time?
- Error states: Are they helpful and non-blaming?
- Success states: Do they confirm and guide next steps?
### 10. Microcopy & Voice
- Is the writing clear and concise?
- Does it sound like a human (the right human for this brand)?
- Are labels and buttons unambiguous?
- Does error copy help users fix the problem?
## Generate Critique Report
Structure your feedback as a design director would:
### Anti-Patterns Verdict
**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest.
### Overall Impression
A brief gut reaction—what works, what doesn't, and the single biggest opportunity.
### What's Working
Highlight 2-3 things done well. Be specific about why they work.
### Priority Issues
The 3-5 most impactful design problems, ordered by importance:
For each issue:
- **What**: Name the problem clearly
- **Why it matters**: How this hurts users or undermines goals
- **Fix**: What to do about it (be concrete)
- **Command**: Which command to use (prefer: /i-quieter, /i-polish, /i-optimize, /i-onboard, /i-normalize, /i-harden, /i-extract, /i-distill, /i-delight, /i-critique, /i-colorize, /i-clarify, /i-bolder, /i-audit, /i-animate, /i-adapt — or other installed skills you're sure exist)
### Minor Observations
Quick notes on smaller issues worth addressing.
### Questions to Consider
Provocative questions that might unlock better solutions:
- "What if the primary action were more prominent?"
- "Does this need to feel this complex?"
- "What would a confident version of this look like?"
**Remember**:
- Be direct—vague feedback wastes everyone's time
- Be specific—"the submit button" not "some elements"
- Say what's wrong AND why it matters to users
- Give concrete suggestions, not just "consider exploring..."
- Prioritize ruthlessly—if everything is important, nothing is
- Don't soften criticism—developers need honest feedback to ship great design
.blackbox/skills/i-delight/SKILL.md
+312
View File
@@ -0,0 +1,312 @@
---
name: i-delight
description: Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful.
---
Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Delight Opportunities
Identify where delight would enhance (not distract from) the experience:
1. **Find natural delight moments**:
- **Success states**: Completed actions (save, send, publish)
- **Empty states**: First-time experiences, onboarding
- **Loading states**: Waiting periods that could be entertaining
- **Achievements**: Milestones, streaks, completions
- **Interactions**: Hover states, clicks, drags
- **Errors**: Softening frustrating moments
- **Easter eggs**: Hidden discoveries for curious users
2. **Understand the context**:
- What's the brand personality? (Playful? Professional? Quirky? Elegant?)
- Who's the audience? (Tech-savvy? Creative? Corporate?)
- What's the emotional context? (Accomplishment? Exploration? Frustration?)
- What's appropriate? (Banking app ≠ gaming app)
3. **Define delight strategy**:
- **Subtle sophistication**: Refined micro-interactions (luxury brands)
- **Playful personality**: Whimsical illustrations and copy (consumer apps)
- **Helpful surprises**: Anticipating needs before users ask (productivity tools)
- **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far.
## Delight Principles
Follow these guidelines:
### Delight Amplifies, Never Blocks
- Delight moments should be quick (< 1 second)
- Never delay core functionality for delight
- Make delight skippable or subtle
- Respect user's time and task focus
### Surprise and Discovery
- Hide delightful details for users to discover
- Reward exploration and curiosity
- Don't announce every delight moment
- Let users share discoveries with others
### Appropriate to Context
- Match delight to emotional moment (celebrate success, empathize with errors)
- Respect the user's state (don't be playful during critical errors)
- Match brand personality and audience expectations
- Cultural sensitivity (what's delightful varies by culture)
### Compound Over Time
- Delight should remain fresh with repeated use
- Vary responses (not same animation every time)
- Reveal deeper layers with continued use
- Build anticipation through patterns
## Delight Techniques
Add personality and joy through these methods:
### Micro-interactions & Animation
**Button delight**:
```css
/* Satisfying button press */
.button {
transition: transform 0.1s, box-shadow 0.1s;
}
.button:active {
transform: translateY(2px);
box-shadow: 0 2px 4px rgba(0,0,0,0.2);
}
/* Ripple effect on click */
/* Smooth lift on hover */
.button:hover {
transform: translateY(-2px);
transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1); /* ease-out-quart */
}
```
**Loading delight**:
- Playful loading animations (not just spinners)
- Personality in loading messages ("Herding pixels..." "Teaching robots to dance...")
- Progress indication with encouraging messages
- Skeleton screens with subtle animations
**Success animations**:
- Checkmark draw animation
- Confetti burst for major achievements
- Gentle scale + fade for confirmation
- Satisfying sound effects (subtle)
**Hover surprises**:
- Icons that animate on hover
- Color shifts or glow effects
- Tooltip reveals with personality
- Cursor changes (custom cursors for branded experiences)
### Personality in Copy
**Playful error messages**:
```
"Error 404"
"This page is playing hide and seek. (And winning)"
"Connection failed"
"Looks like the internet took a coffee break. Want to retry?"
```
**Encouraging empty states**:
```
"No projects"
"Your canvas awaits. Create something amazing."
"No messages"
"Inbox zero! You're crushing it today."
```
**Playful labels & tooltips**:
```
"Delete"
"Send to void" (for playful brand)
"Help"
"Rescue me" (tooltip)
```
**IMPORTANT**: Match copy personality to brand. Banks shouldn't be wacky, but they can be warm.
### Illustrations & Visual Personality
**Custom illustrations**:
- Empty state illustrations (not stock icons)
- Error state illustrations (friendly monsters, quirky characters)
- Loading state illustrations (animated characters)
- Success state illustrations (celebrations)
**Icon personality**:
- Custom icon set matching brand personality
- Animated icons (subtle motion on hover/click)
- Illustrative icons (more detailed than generic)
- Consistent style across all icons
**Background effects**:
- Subtle particle effects
- Gradient mesh backgrounds
- Geometric patterns
- Parallax depth
- Time-of-day themes (morning vs night)
### Satisfying Interactions
**Drag and drop delight**:
- Lift effect on drag (shadow, scale)
- Snap animation when dropped
- Satisfying placement sound
- Undo toast ("Dropped in wrong place? [Undo]")
**Toggle switches**:
- Smooth slide with spring physics
- Color transition
- Haptic feedback on mobile
- Optional sound effect
**Progress & achievements**:
- Streak counters with celebratory milestones
- Progress bars that "celebrate" at 100%
- Badge unlocks with animation
- Playful stats ("You're on fire! 5 days in a row")
**Form interactions**:
- Input fields that animate on focus
- Checkboxes that bounce when checked
- Success state that celebrates valid input
- Auto-grow textareas
### Sound Design
**Subtle audio cues** (when appropriate):
- Notification sounds (distinctive but not annoying)
- Success sounds (satisfying "ding")
- Error sounds (empathetic, not harsh)
- Typing sounds for chat/messaging
- Ambient background audio (very subtle)
**IMPORTANT**:
- Respect system sound settings
- Provide mute option
- Keep volumes quiet (subtle cues, not alarms)
- Don't play on every interaction (sound fatigue is real)
### Easter Eggs & Hidden Delights
**Discovery rewards**:
- Konami code unlocks special theme
- Hidden keyboard shortcuts (Cmd+K for special features)
- Hover reveals on logos or illustrations
- Alt text jokes on images (for screen reader users too!)
- Console messages for developers ("Like what you see? We're hiring!")
**Seasonal touches**:
- Holiday themes (subtle, tasteful)
- Seasonal color shifts
- Weather-based variations
- Time-based changes (dark at night, light during day)
**Contextual personality**:
- Different messages based on time of day
- Responses to specific user actions
- Randomized variations (not same every time)
- Progressive reveals with continued use
### Loading & Waiting States
**Make waiting engaging**:
- Interesting loading messages that rotate
- Progress bars with personality
- Mini-games during long loads
- Fun facts or tips while waiting
- Countdown with encouraging messages
```
Loading messages rotation:
- "Waking up the servers..."
- "Teaching robots to dance..."
- "Consulting the magic 8-ball..."
- "Counting backwards from infinity..."
```
### Celebration Moments
**Success celebrations**:
- Confetti for major milestones
- Animated checkmarks for completions
- Progress bar celebrations at 100%
- "Achievement unlocked" style notifications
- Personalized messages ("You published your 10th article!")
**Milestone recognition**:
- First-time actions get special treatment
- Streak tracking and celebration
- Progress toward goals
- Anniversary celebrations
## Implementation Patterns
**Animation libraries**:
- Framer Motion (React)
- GSAP (universal)
- Lottie (After Effects animations)
- Canvas confetti (party effects)
**Sound libraries**:
- Howler.js (audio management)
- Use-sound (React hook)
**Physics libraries**:
- React Spring (spring physics)
- Popmotion (animation primitives)
**IMPORTANT**: File size matters. Compress images, optimize animations, lazy load delight features.
**NEVER**:
- Delay core functionality for delight
- Force users through delightful moments (make skippable)
- Use delight to hide poor UX
- Overdo it (less is more)
- Ignore accessibility (animate responsibly, provide alternatives)
- Make every interaction delightful (special moments should be special)
- Sacrifice performance for delight
- Be inappropriate for context (read the room)
## Verify Delight Quality
Test that delight actually delights:
- **User reactions**: Do users smile? Share screenshots?
- **Doesn't annoy**: Still pleasant after 100th time?
- **Doesn't block**: Can users opt out or skip?
- **Performant**: No jank, no slowdown
- **Appropriate**: Matches brand and context
- **Accessible**: Works with reduced motion, screen readers
Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.
.blackbox/skills/i-distill/SKILL.md
+132
View File
@@ -0,0 +1,132 @@
---
name: i-distill
description: Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean.
---
Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Simplifying the wrong things destroys usability.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Current State
Analyze what makes the design feel complex or cluttered:
1. **Identify complexity sources**:
- **Too many elements**: Competing buttons, redundant information, visual clutter
- **Excessive variation**: Too many colors, fonts, sizes, styles without purpose
- **Information overload**: Everything visible at once, no progressive disclosure
- **Visual noise**: Unnecessary borders, shadows, backgrounds, decorations
- **Confusing hierarchy**: Unclear what matters most
- **Feature creep**: Too many options, actions, or paths forward
2. **Find the essence**:
- What's the primary user goal? (There should be ONE)
- What's actually necessary vs nice-to-have?
- What can be removed, hidden, or combined?
- What's the 20% that delivers 80% of value?
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.
## Plan Simplification
Create a ruthless editing strategy:
- **Core purpose**: What's the ONE thing this should accomplish?
- **Essential elements**: What's truly necessary to achieve that purpose?
- **Progressive disclosure**: What can be hidden until needed?
- **Consolidation opportunities**: What can be combined or integrated?
**IMPORTANT**: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless.
## Simplify the Design
Systematically remove complexity across these dimensions:
### Information Architecture
- **Reduce scope**: Remove secondary actions, optional features, redundant information
- **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows)
- **Combine related actions**: Merge similar buttons, consolidate forms, group related content
- **Clear hierarchy**: ONE primary action, few secondary actions, everything else tertiary or hidden
- **Remove redundancy**: If it's said elsewhere, don't repeat it here
### Visual Simplification
- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
- **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights
- **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function
- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards
- **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead
- **Consistent spacing**: Use one spacing scale, remove arbitrary gaps
### Layout Simplification
- **Linear flow**: Replace complex grids with simple vertical flow where possible
- **Remove sidebars**: Move secondary content inline or hide it
- **Full-width**: Use available space generously instead of complex multi-column layouts
- **Consistent alignment**: Pick left or center, stick with it
- **Generous white space**: Let content breathe, don't pack everything tight
### Interaction Simplification
- **Reduce choices**: Fewer buttons, fewer options, clearer path forward (paradox of choice is real)
- **Smart defaults**: Make common choices automatic, only ask when necessary
- **Inline actions**: Replace modal flows with inline editing where possible
- **Remove steps**: Can signup be one step instead of three? Can checkout be simplified?
- **Clear CTAs**: ONE obvious next step, not five competing actions
### Content Simplification
- **Shorter copy**: Cut every sentence in half, then do it again
- **Active voice**: "Save changes" not "Changes will be saved"
- **Remove jargon**: Plain language always wins
- **Scannable structure**: Short paragraphs, bullet points, clear headings
- **Essential information only**: Remove marketing fluff, legalese, hedging
- **Remove redundant copy**: No headers restating intros, no repeated explanations, say it once
### Code Simplification
- **Remove unused code**: Dead CSS, unused components, orphaned files
- **Flatten component trees**: Reduce nesting depth
- **Consolidate styles**: Merge similar styles, use utilities consistently
- **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases?
**NEVER**:
- Remove necessary functionality (simplicity ≠ feature-less)
- Sacrifice accessibility for simplicity (clear labels and ARIA still required)
- Make things so simple they're unclear (mystery ≠ minimalism)
- Remove information users need to make decisions
- Eliminate hierarchy completely (some things should stand out)
- Oversimplify complex domains (match complexity to actual task complexity)
## Verify Simplification
Ensure simplification improves usability:
- **Faster task completion**: Can users accomplish goals more quickly?
- **Reduced cognitive load**: Is it easier to understand what to do?
- **Still complete**: Are all necessary features still accessible?
- **Clearer hierarchy**: Is it obvious what matters most?
- **Better performance**: Does simpler design load faster?
## Document Removed Complexity
If you removed features or options:
- Document why they were removed
- Consider if they need alternative access points
- Note any user feedback to monitor
Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
.blackbox/skills/i-extract/SKILL.md
+89
View File
@@ -0,0 +1,89 @@
---
name: i-extract
description: Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library.
---
Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse.
## Discover
Analyze the target area to identify extraction opportunities:
1. **Find the design system**: Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure:
- Component organization and naming conventions
- Design token structure (if any)
- Documentation patterns
- Import/export conventions
**CRITICAL**: If no design system exists, ask before creating one. Understand the preferred location and structure first.
2. **Identify patterns**: Look for:
- **Repeated components**: Similar UI patterns used multiple times (buttons, cards, inputs, etc.)
- **Hard-coded values**: Colors, spacing, typography, shadows that should be tokens
- **Inconsistent variations**: Multiple implementations of the same concept (3 different button styles)
- **Reusable patterns**: Layout patterns, composition patterns, interaction patterns worth systematizing
3. **Assess value**: Not everything should be extracted. Consider:
- Is this used 3+ times, or likely to be reused?
- Would systematizing this improve consistency?
- Is this a general pattern or context-specific?
- What's the maintenance cost vs benefit?
## Plan Extraction
Create a systematic extraction plan:
- **Components to extract**: Which UI elements become reusable components?
- **Tokens to create**: Which hard-coded values become design tokens?
- **Variants to support**: What variations does each component need?
- **Naming conventions**: Component names, token names, prop names that match existing patterns
- **Migration path**: How to refactor existing uses to consume the new shared versions
**IMPORTANT**: Design systems grow incrementally. Extract what's clearly reusable now, not everything that might someday be reusable.
## Extract & Enrich
Build improved, reusable versions:
- **Components**: Create well-designed components with:
- Clear props API with sensible defaults
- Proper variants for different use cases
- Accessibility built in (ARIA, keyboard navigation, focus management)
- Documentation and usage examples
- **Design tokens**: Create tokens with:
- Clear naming (primitive vs semantic)
- Proper hierarchy and organization
- Documentation of when to use each token
- **Patterns**: Document patterns with:
- When to use this pattern
- Code examples
- Variations and combinations
**NEVER**:
- Extract one-off, context-specific implementations without generalization
- Create components so generic they're useless
- Extract without considering existing design system conventions
- Skip proper TypeScript types or prop documentation
- Create tokens for every single value (tokens should have semantic meaning)
## Migrate
Replace existing uses with the new shared versions:
- **Find all instances**: Search for the patterns you've extracted
- **Replace systematically**: Update each use to consume the shared version
- **Test thoroughly**: Ensure visual and functional parity
- **Delete dead code**: Remove the old implementations
## Document
Update design system documentation:
- Add new components to the component library
- Document token usage and values
- Add examples and guidelines
- Update any Storybook or component catalog
Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.
.blackbox/skills/i-frontend-design/SKILL.md
+127
View File
@@ -0,0 +1,127 @@
---
name: i-frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics.
license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
---
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
## Design Direction
Commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work—the key is intentionality, not intensity.
Then implement working code that is:
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail
## Frontend Aesthetics Guidelines
### Typography
→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
**DO**: Use a modular type scale with fluid sizing (clamp)
**DO**: Vary font weights and sizes to create clear visual hierarchy
**DON'T**: Use overused fonts—Inter, Roboto, Arial, Open Sans, system defaults
**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes
**DON'T**: Put large icons with rounded corners above every heading—they rarely add value and make sites look templated
### Color & Theme
→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*
Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes
**DO**: Tint your neutrals toward your brand hue—even a subtle hint creates subconscious cohesion
**DON'T**: Use gray text on colored backgrounds—it looks washed out; use a shade of the background color instead
**DON'T**: Use pure black (#000) or pure white (#fff)—always tint; pure black/white never appears in nature
**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
**DON'T**: Use gradient text for "impact"—especially on metrics or headings; it's decorative rather than meaningful
**DON'T**: Default to dark mode with glowing accents—it looks "cool" without requiring actual design decisions
### Layout & Space
→ *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.*
Create visual rhythm through varied spacing—not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
**DO**: Create visual rhythm through varied spacing—tight groupings, generous separations
**DO**: Use fluid spacing with clamp() that breathes on larger screens
**DO**: Use asymmetry and unexpected compositions; break the grid intentionally for emphasis
**DON'T**: Wrap everything in cards—not everything needs a container
**DON'T**: Nest cards inside cards—visual noise, flatten the hierarchy
**DON'T**: Use identical card grids—same-sized cards with icon + heading + text, repeated endlessly
**DON'T**: Use the hero metric layout template—big number, small label, supporting stats, gradient accent
**DON'T**: Center everything—left-aligned text with asymmetric layouts feels more designed
**DON'T**: Use the same spacing everywhere—without rhythm, layouts feel monotonous
### Visual Details
**DO**: Use intentional, purposeful decorative elements that reinforce brand
**DON'T**: Use glassmorphism everywhere—blur effects, glass cards, glow borders used decoratively rather than purposefully
**DON'T**: Use rounded elements with thick colored border on one side—a lazy accent that almost never looks intentional
**DON'T**: Use sparklines as decoration—tiny charts that look sophisticated but convey nothing meaningful
**DON'T**: Use rounded rectangles with generic drop shadows—safe, forgettable, could be any AI output
**DON'T**: Use modals unless there's truly no better alternative—modals are lazy
### Motion
→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
**DO**: Use motion to convey state changes—entrances, exits, feedback
**DO**: Use exponential easing (ease-out-quart/quint/expo) for natural deceleration
**DO**: For height animations, use grid-template-rows transitions instead of animating height directly
**DON'T**: Animate layout properties (width, height, padding, margin)—use transform and opacity only
**DON'T**: Use bounce or elastic easing—they feel dated and tacky; real objects decelerate smoothly
### Interaction
→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.*
Make interactions feel fast. Use optimistic UI—update immediately, sync later.
**DO**: Use progressive disclosure—start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions)
**DO**: Design empty states that teach the interface, not just say "nothing here"
**DO**: Make every interactive surface feel intentional and responsive
**DON'T**: Repeat the same information—redundant headers, intros that restate the heading
**DON'T**: Make every button primary—use ghost buttons, text links, secondary styles; hierarchy matters
### Responsive
→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.*
**DO**: Use container queries (@container) for component-level responsiveness
**DO**: Adapt the interface for different contexts—don't just shrink it
**DON'T**: Hide critical functionality on mobile—adapt the interface, don't amputate it
### UX Writing
→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
**DO**: Make every word earn its place
**DON'T**: Repeat information users can already see
---
## The AI Slop Test
**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
A distinctive interface should make someone ask "how was this made?" not "which AI made this?"
Review the DON'T guidelines above—they are the fingerprints of AI-generated work from 2024-2025.
---
## Implementation Principles
Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details.
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
Remember: GPT is capable of extraordinary creative work. Don't hold back—show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
.blackbox/skills/i-frontend-design/reference/color-and-contrast.md
+132
View File
@@ -0,0 +1,132 @@
# Color & Contrast
## Color Spaces: Use OKLCH
**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
```css
/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */
--color-primary: oklch(60% 0.15 250); /* Blue */
--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */
--color-primary-dark: oklch(35% 0.12 250); /* Same hue, darker */
```
**Key insight**: As you move toward white or black, reduce chroma (saturation). High chroma at extreme lightness looks garish. A light blue at 85% lightness needs ~0.08 chroma, not the 0.15 of your base color.
## Building Functional Palettes
### The Tinted Neutral Trap
**Pure gray is dead.** Add a subtle hint of your brand hue to all neutrals:
```css
/* Dead grays */
--gray-100: oklch(95% 0 0); /* No personality */
--gray-900: oklch(15% 0 0);
/* Warm-tinted grays (add brand warmth) */
--gray-100: oklch(95% 0.01 60); /* Hint of warmth */
--gray-900: oklch(15% 0.01 60);
/* Cool-tinted grays (tech, professional) */
--gray-100: oklch(95% 0.01 250); /* Hint of blue */
--gray-900: oklch(15% 0.01 250);
```
The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and your UI.
### Palette Structure
A complete system needs:
| Role | Purpose | Example |
|------|---------|---------|
| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise.
### The 60-30-10 Rule (Applied Correctly)
This rule is about **visual weight**, not pixel count:
- **60%**: Neutral backgrounds, white space, base surfaces
- **30%**: Secondary colors—text, borders, inactive states
- **10%**: Accent—CTAs, highlights, focus states
The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
## Contrast & Accessibility
### WCAG Requirements
| Content Type | AA Minimum | AAA Target |
|--------------|------------|------------|
| Body text | 4.5:1 | 7:1 |
| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
| UI components, icons | 3:1 | 4.5:1 |
| Non-essential decorations | None | None |
**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.
### Dangerous Color Combinations
These commonly fail contrast or cause readability issues:
- Light gray text on white (the #1 accessibility fail)
- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
- Red text on green background (or vice versa)—8% of men can't distinguish these
- Blue text on red background (vibrates visually)
- Yellow text on white (almost always fails)
- Thin light text on images (unpredictable contrast)
### Never Use Pure Gray or Pure Black
Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
### Testing
Don't trust your eyes. Use tools:
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
- Browser DevTools → Rendering → Emulate vision deficiencies
- [Polypane](https://polypane.app/) for real-time testing
## Theming: Light & Dark Mode
### Dark Mode Is Not Inverted Light Mode
You can't just swap colors. Dark mode requires different design decisions:
| Light Mode | Dark Mode |
|------------|-----------|
| Shadows for depth | Lighter surfaces for depth (no shadows) |
| Dark text on light | Light text on dark (reduce font weight) |
| Vibrant accents | Desaturate accents slightly |
| White backgrounds | Never pure black—use dark gray (oklch 12-18%) |
```css
/* Dark mode depth via surface color, not shadow */
:root[data-theme="dark"] {
--surface-1: oklch(15% 0.01 250);
--surface-2: oklch(20% 0.01 250); /* "Higher" = lighter */
--surface-3: oklch(25% 0.01 250);
/* Reduce text weight slightly */
--body-weight: 350; /* Instead of 400 */
}
```
### Token Hierarchy
Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same.
## Alpha Is A Design Smell
Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.
---
**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).
.blackbox/skills/i-frontend-design/reference/interaction-design.md
+123
View File
@@ -0,0 +1,123 @@
# Interaction Design
## The Eight Interactive States
Every interactive element needs these states designed:
| State | When | Visual Treatment |
|-------|------|------------------|
| **Default** | At rest | Base styling |
| **Hover** | Pointer over (not touch) | Subtle lift, color shift |
| **Focus** | Keyboard/programmatic focus | Visible ring (see below) |
| **Active** | Being pressed | Pressed in, darker |
| **Disabled** | Not interactive | Reduced opacity, no pointer |
| **Loading** | Processing | Spinner, skeleton |
| **Error** | Invalid state | Red border, icon, message |
| **Success** | Completed | Green check, confirmation |
**The common miss**: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states.
## Focus Rings: Do Them Right
**Never `outline: none` without replacement.** It's an accessibility violation. Instead, use `:focus-visible` to show focus only for keyboard users:
```css
/* Hide focus ring for mouse/touch */
button:focus {
outline: none;
}
/* Show focus ring for keyboard */
button:focus-visible {
outline: 2px solid var(--color-accent);
outline-offset: 2px;
}
```
**Focus ring design**:
- High contrast (3:1 minimum against adjacent colors)
- 2-3px thick
- Offset from element (not inside it)
- Consistent across all interactive elements
## Form Design: The Non-Obvious
**Placeholders aren't labels**—they disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
## Loading States
**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**—they preview content shape and feel faster than generic spinners.
## Modals: The Inert Approach
Focus trapping in modals used to require complex JavaScript. Now use the `inert` attribute:
```html
<!-- When modal is open -->
<main inert>
<!-- Content behind modal can't be focused or clicked -->
</main>
<dialog open>
<h2>Modal Title</h2>
<!-- Focus stays inside modal -->
</dialog>
```
Or use the native `<dialog>` element:
```javascript
const dialog = document.querySelector('dialog');
dialog.showModal(); // Opens with focus trap, closes on Escape
```
## The Popover API
For tooltips, dropdowns, and non-modal overlays, use native popovers:
```html
<button popovertarget="menu">Open menu</button>
<div id="menu" popover>
<button>Option 1</button>
<button>Option 2</button>
</div>
```
**Benefits**: Light-dismiss (click outside closes), proper stacking, no z-index wars, accessible by default.
## Destructive Actions: Undo > Confirm
**Undo is better than confirmation dialogs**—users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
## Keyboard Navigation Patterns
### Roving Tabindex
For component groups (tabs, menu items, radio groups), one item is tabbable; arrow keys move within:
```html
<div role="tablist">
<button role="tab" tabindex="0">Tab 1</button>
<button role="tab" tabindex="-1">Tab 2</button>
<button role="tab" tabindex="-1">Tab 3</button>
</div>
```
Arrow keys move `tabindex="0"` between items. Tab moves to the next component entirely.
### Skip Links
Provide skip links (`<a href="#main-content">Skip to main content</a>`) for keyboard users to jump past navigation. Hide off-screen, show on focus.
## Gesture Discoverability
Swipe-to-delete and similar gestures are invisible. Hint at their existence:
- **Partially reveal**: Show delete button peeking from edge
- **Onboarding**: Coach marks on first use
- **Alternative**: Always provide a visible fallback (menu with "Delete")
Don't rely on gestures as the only way to perform actions.
---
**Avoid**: Removing focus indicators without alternatives. Using placeholder text as labels. Touch targets <44x44px. Generic error messages. Custom controls without ARIA/keyboard support.
.blackbox/skills/i-frontend-design/reference/motion-design.md
+99
View File
@@ -0,0 +1,99 @@
# Motion Design
## Duration: The 100/300/500 Rule
Timing matters more than easing. These durations feel right for most UI:
| Duration | Use Case | Examples |
|----------|----------|----------|
| **100-150ms** | Instant feedback | Button press, toggle, color change |
| **200-300ms** | State changes | Menu open, tooltip, hover states |
| **300-500ms** | Layout changes | Accordion, modal, drawer |
| **500-800ms** | Entrance animations | Page load, hero reveals |
**Exit animations are faster than entrances**—use ~75% of enter duration.
## Easing: Pick the Right Curve
**Don't use `ease`.** It's a compromise that's rarely optimal. Instead:
| Curve | Use For | CSS |
|-------|---------|-----|
| **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` |
| **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
| **ease-in-out** | State toggles (there → back) | `cubic-bezier(0.65, 0, 0.35, 1)` |
**For micro-interactions, use exponential curves**—they feel natural because they mimic real physics (friction, deceleration):
```css
/* Quart out - smooth, refined (recommended default) */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
/* Quint out - slightly more dramatic */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);
/* Expo out - snappy, confident */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
```
**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects don't bounce when they stop—they decelerate smoothly. Overshoot effects draw attention to the animation itself rather than the content.
## The Only Two Properties You Should Animate
**transform** and **opacity** only—everything else causes layout recalculation. For height animations (accordions), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly.
## Staggered Animations
Use CSS custom properties for cleaner stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"` on each item. **Cap total stagger time**—10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
## Reduced Motion
This is not optional. Vestibular disorders affect ~35% of adults over 40.
```css
/* Define animations normally */
.card {
animation: slide-up 500ms ease-out;
}
/* Provide alternative for reduced motion */
@media (prefers-reduced-motion: reduce) {
.card {
animation: fade-in 200ms ease-out; /* Crossfade instead of motion */
}
}
/* Or disable entirely */
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
}
}
```
**What to preserve**: Functional animations like progress bars, loading spinners (slowed down), and focus indicators should still work—just without spatial movement.
## Perceived Performance
**Nobody cares how fast your site is—just how fast it feels.** Perception can be as effective as actual performance.
**The 80ms threshold**: Our brains buffer sensory input for ~80ms to synchronize perception. Anything under 80ms feels instant and simultaneous. This is your target for micro-interactions.
**Active vs passive time**: Passive waiting (staring at a spinner) feels longer than active engagement. Strategies to shift the balance:
- **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
- **Early completion**: Show content progressively—don't wait for everything. Video buffering, progressive images, streaming HTML.
- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Instagram likes work offline—the UI updates instantly, syncs later. Use for low-stakes actions; avoid for payments or destructive operations.
**Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances, but ease-in toward a task's end compresses perceived time.
**Caution**: Too-fast responses can decrease perceived value. Users may distrust instant results for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.
## Performance
Don't use `will-change` preemptively—only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once. Create motion tokens for consistency (durations, easings, common transitions).
---
**Avoid**: Animating everything (animation fatigue is real). Using >500ms for UI feedback. Ignoring `prefers-reduced-motion`. Using animation to hide slow loading.
.blackbox/skills/i-frontend-design/reference/responsive-design.md
+114
View File
@@ -0,0 +1,114 @@
# Responsive Design
## Mobile-First: Write It Right
Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
## Breakpoints: Content-Driven
Don't chase device sizes—let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
## Detect Input Method, Not Just Screen Size
**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard—use pointer and hover queries:
```css
/* Fine pointer (mouse, trackpad) */
@media (pointer: fine) {
.button { padding: 8px 16px; }
}
/* Coarse pointer (touch, stylus) */
@media (pointer: coarse) {
.button { padding: 12px 20px; } /* Larger touch target */
}
/* Device supports hover */
@media (hover: hover) {
.card:hover { transform: translateY(-2px); }
}
/* Device doesn't support hover (touch) */
@media (hover: none) {
.card { /* No hover state - use active instead */ }
}
```
**Critical**: Don't rely on hover for functionality. Touch users can't hover.
## Safe Areas: Handle the Notch
Modern phones have notches, rounded corners, and home indicators. Use `env()`:
```css
body {
padding-top: env(safe-area-inset-top);
padding-bottom: env(safe-area-inset-bottom);
padding-left: env(safe-area-inset-left);
padding-right: env(safe-area-inset-right);
}
/* With fallback */
.footer {
padding-bottom: max(1rem, env(safe-area-inset-bottom));
}
```
**Enable viewport-fit** in your meta tag:
```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
```
## Responsive Images: Get It Right
### srcset with Width Descriptors
```html
<img
src="hero-800.jpg"
srcset="
hero-400.jpg 400w,
hero-800.jpg 800w,
hero-1200.jpg 1200w
"
sizes="(max-width: 768px) 100vw, 50vw"
alt="Hero image"
>
```
**How it works**:
- `srcset` lists available images with their actual widths (`w` descriptors)
- `sizes` tells the browser how wide the image will display
- Browser picks the best file based on viewport width AND device pixel ratio
### Picture Element for Art Direction
When you need different crops/compositions (not just resolutions):
```html
<picture>
<source media="(min-width: 768px)" srcset="wide.jpg">
<source media="(max-width: 767px)" srcset="tall.jpg">
<img src="fallback.jpg" alt="...">
</picture>
```
## Layout Adaptation Patterns
**Navigation**: Three stages—hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
## Testing: Don't Trust DevTools Alone
DevTools device emulation is useful for layout but misses:
- Actual touch interactions
- Real CPU/memory constraints
- Network latency patterns
- Font rendering differences
- Browser chrome/keyboard appearances
**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
---
**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.
.blackbox/skills/i-frontend-design/reference/spatial-design.md
+100
View File
@@ -0,0 +1,100 @@
# Spatial Design
## Spacing Systems
### Use 4pt Base, Not 8pt
8pt systems are too coarse—you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
### Name Tokens Semantically
Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing—it eliminates margin collapse and cleanup hacks.
## Grid Systems
### The Self-Adjusting Grid
Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch. For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
## Visual Hierarchy
### The Squint Test
Blur your eyes (or screenshot and blur). Can you still identify:
- The most important element?
- The second most important?
- Clear groupings?
If everything looks the same weight blurred, you have a hierarchy problem.
### Hierarchy Through Multiple Dimensions
Don't rely on size alone. Combine:
| Tool | Strong Hierarchy | Weak Hierarchy |
|------|------------------|----------------|
| **Size** | 3:1 ratio or more | <2:1 ratio |
| **Weight** | Bold vs Regular | Medium vs Regular |
| **Color** | High contrast | Similar tones |
| **Position** | Top/left (primary) | Bottom/right |
| **Space** | Surrounded by white space | Crowded |
**The best hierarchy uses 2-3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
### Cards Are Not Required
Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when content is truly distinct and actionable, items need visual comparison in a grid, or content needs clear interaction boundaries. **Never nest cards inside cards**—use spacing, typography, and subtle dividers for hierarchy within a card.
## Container Queries
Viewport queries are for page layouts. **Container queries are for components**:
```css
.card-container {
container-type: inline-size;
}
.card {
display: grid;
gap: var(--space-md);
}
/* Card layout changes based on its container, not viewport */
@container (min-width: 400px) {
.card {
grid-template-columns: 120px 1fr;
}
}
```
**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands—automatically, without viewport hacks.
## Optical Adjustments
Text at `margin-left: 0` looks indented due to letterform whitespace—use negative margin (`-0.05em`) to optically align. Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction.
### Touch Targets vs Visual Size
Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
```css
.icon-button {
width: 24px; /* Visual size */
height: 24px;
position: relative;
}
.icon-button::before {
content: '';
position: absolute;
inset: -10px; /* Expand tap target to 44px */
}
```
## Depth & Elevation
Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers. For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle—if you can clearly see it, it's probably too strong.
---
**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone - combine size, weight, color, and space.
.blackbox/skills/i-frontend-design/reference/typography.md
+131
View File
@@ -0,0 +1,131 @@
# Typography
## Classic Typography Principles
### Vertical Rhythm
Your line-height should be the base unit for ALL vertical spacing. If body text has `line-height: 1.5` on `16px` type (= 24px), spacing values should be multiples of 24px. This creates subconscious harmony—text and space share a mathematical foundation.
### Modular Scale & Hierarchy
The common mistake: too many font sizes that are too close together (14px, 15px, 16px, 18px...). This creates muddy hierarchy.
**Use fewer sizes with more contrast.** A 5-size system covers most needs:
| Role | Typical Ratio | Use Case |
|------|---------------|----------|
| xs | 0.75rem | Captions, legal |
| sm | 0.875rem | Secondary UI, metadata |
| base | 1rem | Body text |
| lg | 1.25-1.5rem | Subheadings, lead text |
| xl+ | 2-4rem | Headlines, hero text |
Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit.
### Readability & Measure
Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.
**Non-obvious**: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05-0.1 to your normal line-height.
## Font Selection & Pairing
### Choosing Distinctive Fonts
**Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal—but if you want distinctive design, look elsewhere.
**Better Google Fonts alternatives**:
- Instead of Inter → **Instrument Sans**, **Plus Jakarta Sans**, **Outfit**
- Instead of Roboto → **Onest**, **Figtree**, **Urbanist**
- Instead of Open Sans → **Source Sans 3**, **Nunito Sans**, **DM Sans**
- For editorial/premium feel → **Fraunces**, **Newsreader**, **Lora**
**System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.
### Pairing Principles
**The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif).
When pairing, contrast on multiple axes:
- Serif + Sans (structure contrast)
- Geometric + Humanist (personality contrast)
- Condensed display + Wide body (proportion contrast)
**Never pair fonts that are similar but not identical** (e.g., two geometric sans-serifs). They create visual tension without clear hierarchy.
### Web Font Loading
The layout shift problem: fonts load late, text reflows, and users see content jump. Here's the fix:
```css
/* 1. Use font-display: swap for visibility */
@font-face {
font-family: 'CustomFont';
src: url('font.woff2') format('woff2');
font-display: swap;
}
/* 2. Match fallback metrics to minimize shift */
@font-face {
font-family: 'CustomFont-Fallback';
src: local('Arial');
size-adjust: 105%; /* Scale to match x-height */
ascent-override: 90%; /* Match ascender height */
descent-override: 20%; /* Match descender depth */
line-gap-override: 10%; /* Match line spacing */
}
body {
font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
}
```
Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
## Modern Web Typography
### Fluid Type
Use `clamp(min, preferred, max)` for fluid typography. The middle value (e.g., `5vw + 1rem`) controls scaling rate—higher vw = faster scaling. Add a rem offset so it doesn't collapse to 0 on small screens.
**When NOT to use fluid type**: Button text, labels, UI elements (should be consistent), very short text, or when you need precise breakpoint control.
### OpenType Features
Most developers don't know these exist. Use them for polish:
```css
/* Tabular numbers for data alignment */
.data-table { font-variant-numeric: tabular-nums; }
/* Proper fractions */
.recipe-amount { font-variant-numeric: diagonal-fractions; }
/* Small caps for abbreviations */
abbr { font-variant-caps: all-small-caps; }
/* Disable ligatures in code */
code { font-variant-ligatures: none; }
/* Enable kerning (usually on by default, but be explicit) */
body { font-kerning: normal; }
```
Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).
## Typography System Architecture
Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.
## Accessibility Considerations
Beyond contrast ratios (which are well-documented), consider:
- **Never disable zoom**: `user-scalable=no` breaks accessibility. If your layout breaks at 200% zoom, fix the layout.
- **Use rem/em for font sizes**: This respects user browser settings. Never `px` for body text.
- **Minimum 16px body text**: Smaller than this strains eyes and fails WCAG on mobile.
- **Adequate touch targets**: Text links need padding or line-height that creates 44px+ tap targets.
---
**Avoid**: More than 2-3 font families per project. Skipping fallback font definitions. Ignoring font loading performance (FOUT/FOIT). Using decorative fonts for body text.
.blackbox/skills/i-frontend-design/reference/ux-writing.md
+107
View File
@@ -0,0 +1,107 @@
# UX Writing
## The Button Label Problem
**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
| Bad | Good | Why |
|-----|------|-----|
| OK | Save changes | Says what will happen |
| Submit | Create account | Outcome-focused |
| Yes | Delete message | Confirms the action |
| Cancel | Keep editing | Clarifies what "cancel" means |
| Click here | Download PDF | Describes the destination |
**For destructive actions**, name the destruction:
- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
- "Delete 5 items" not "Delete selected" (show the count)
## Error Messages: The Formula
Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
### Error Message Templates
| Situation | Template |
|-----------|----------|
| **Format error** | "[Field] needs to be [format]. Example: [example]" |
| **Missing required** | "Please enter [what's missing]" |
| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
### Don't Blame the User
Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
## Empty States Are Opportunities
Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
## Voice vs Tone
**Voice** is your brand's personality—consistent everywhere.
**Tone** adapts to the moment.
| Moment | Tone Shift |
|--------|------------|
| Success | Celebratory, brief: "Done! Your changes are live." |
| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
| Loading | Reassuring: "Saving your work..." |
| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
## Writing for Accessibility
**Link text** must have standalone meaning—"View pricing plans" not "Click here". **Alt text** describes information, not the image—"Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
## Writing for Translation
### Plan for Expansion
German text is ~30% longer than English. Allocate space:
| Language | Expansion |
|----------|-----------|
| German | +30% |
| French | +20% |
| Finnish | +30-40% |
| Chinese | -30% (fewer chars, but same width) |
### Translation-Friendly Patterns
Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
## Consistency: The Terminology Problem
Pick one term and stick with it:
| Inconsistent | Consistent |
|--------------|------------|
| Delete / Remove / Trash | Delete |
| Settings / Preferences / Options | Settings |
| Sign in / Log in / Enter | Sign in |
| Create / Add / New | Create |
Build a terminology glossary and enforce it. Variety creates confusion.
## Avoid Redundant Copy
If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
## Loading States
Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
## Confirmation Dialogs: Use Sparingly
Most confirmation dialogs are design failures—consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
## Form Instructions
Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
---
**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.
.blackbox/skills/i-harden/SKILL.md
+352
View File
@@ -0,0 +1,352 @@
---
name: i-harden
description: Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready.
---
Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.
## Assess Hardening Needs
Identify weaknesses and edge cases:
1. **Test with extreme inputs**:
- Very long text (names, descriptions, titles)
- Very short text (empty, single character)
- Special characters (emoji, RTL text, accents)
- Large numbers (millions, billions)
- Many items (1000+ list items, 50+ options)
- No data (empty states)
2. **Test error scenarios**:
- Network failures (offline, slow, timeout)
- API errors (400, 401, 403, 404, 500)
- Validation errors
- Permission errors
- Rate limiting
- Concurrent operations
3. **Test internationalization**:
- Long translations (German is often 30% longer than English)
- RTL languages (Arabic, Hebrew)
- Character sets (Chinese, Japanese, Korean, emoji)
- Date/time formats
- Number formats (1,000 vs 1.000)
- Currency symbols
**CRITICAL**: Designs that only work with perfect data aren't production-ready. Harden against reality.
## Hardening Dimensions
Systematically improve resilience:
### Text Overflow & Wrapping
**Long text handling**:
```css
/* Single line with ellipsis */
.truncate {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* Multi-line with clamp */
.line-clamp {
display: -webkit-box;
-webkit-line-clamp: 3;
-webkit-box-orient: vertical;
overflow: hidden;
}
/* Allow wrapping */
.wrap {
word-wrap: break-word;
overflow-wrap: break-word;
hyphens: auto;
}
```
**Flex/Grid overflow**:
```css
/* Prevent flex items from overflowing */
.flex-item {
min-width: 0; /* Allow shrinking below content size */
overflow: hidden;
}
/* Prevent grid items from overflowing */
.grid-item {
min-width: 0;
min-height: 0;
}
```
**Responsive text sizing**:
- Use `clamp()` for fluid typography
- Set minimum readable sizes (14px on mobile)
- Test text scaling (zoom to 200%)
- Ensure containers expand with text
### Internationalization (i18n)
**Text expansion**:
- Add 30-40% space budget for translations
- Use flexbox/grid that adapts to content
- Test with longest language (usually German)
- Avoid fixed widths on text containers
```jsx
// ❌ Bad: Assumes short English text
<button className="w-24">Submit</button>
// ✅ Good: Adapts to content
<button className="px-4 py-2">Submit</button>
```
**RTL (Right-to-Left) support**:
```css
/* Use logical properties */
margin-inline-start: 1rem; /* Not margin-left */
padding-inline: 1rem; /* Not padding-left/right */
border-inline-end: 1px solid; /* Not border-right */
/* Or use dir attribute */
[dir="rtl"] .arrow { transform: scaleX(-1); }
```
**Character set support**:
- Use UTF-8 encoding everywhere
- Test with Chinese/Japanese/Korean (CJK) characters
- Test with emoji (they can be 2-4 bytes)
- Handle different scripts (Latin, Cyrillic, Arabic, etc.)
**Date/Time formatting**:
```javascript
// ✅ Use Intl API for proper formatting
new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024
new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024
new Intl.NumberFormat('en-US', {
style: 'currency',
currency: 'USD'
}).format(1234.56); // $1,234.56
```
**Pluralization**:
```javascript
// ❌ Bad: Assumes English pluralization
`${count} item${count !== 1 ? 's' : ''}`
// ✅ Good: Use proper i18n library
t('items', { count }) // Handles complex plural rules
```
### Error Handling
**Network errors**:
- Show clear error messages
- Provide retry button
- Explain what happened
- Offer offline mode (if applicable)
- Handle timeout scenarios
```jsx
// Error states with recovery
{error && (
<ErrorMessage>
<p>Failed to load data. {error.message}</p>
<button onClick={retry}>Try again</button>
</ErrorMessage>
)}
```
**Form validation errors**:
- Inline errors near fields
- Clear, specific messages
- Suggest corrections
- Don't block submission unnecessarily
- Preserve user input on error
**API errors**:
- Handle each status code appropriately
- 400: Show validation errors
- 401: Redirect to login
- 403: Show permission error
- 404: Show not found state
- 429: Show rate limit message
- 500: Show generic error, offer support
**Graceful degradation**:
- Core functionality works without JavaScript
- Images have alt text
- Progressive enhancement
- Fallbacks for unsupported features
### Edge Cases & Boundary Conditions
**Empty states**:
- No items in list
- No search results
- No notifications
- No data to display
- Provide clear next action
**Loading states**:
- Initial load
- Pagination load
- Refresh
- Show what's loading ("Loading your projects...")
- Time estimates for long operations
**Large datasets**:
- Pagination or virtual scrolling
- Search/filter capabilities
- Performance optimization
- Don't load all 10,000 items at once
**Concurrent operations**:
- Prevent double-submission (disable button while loading)
- Handle race conditions
- Optimistic updates with rollback
- Conflict resolution
**Permission states**:
- No permission to view
- No permission to edit
- Read-only mode
- Clear explanation of why
**Browser compatibility**:
- Polyfills for modern features
- Fallbacks for unsupported CSS
- Feature detection (not browser detection)
- Test in target browsers
### Input Validation & Sanitization
**Client-side validation**:
- Required fields
- Format validation (email, phone, URL)
- Length limits
- Pattern matching
- Custom validation rules
**Server-side validation** (always):
- Never trust client-side only
- Validate and sanitize all inputs
- Protect against injection attacks
- Rate limiting
**Constraint handling**:
```html
<!-- Set clear constraints -->
<input
type="text"
maxlength="100"
pattern="[A-Za-z0-9]+"
required
aria-describedby="username-hint"
/>
<small id="username-hint">
Letters and numbers only, up to 100 characters
</small>
```
### Accessibility Resilience
**Keyboard navigation**:
- All functionality accessible via keyboard
- Logical tab order
- Focus management in modals
- Skip links for long content
**Screen reader support**:
- Proper ARIA labels
- Announce dynamic changes (live regions)
- Descriptive alt text
- Semantic HTML
**Motion sensitivity**:
```css
@media (prefers-reduced-motion: reduce) {
* {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
```
**High contrast mode**:
- Test in Windows high contrast mode
- Don't rely only on color
- Provide alternative visual cues
### Performance Resilience
**Slow connections**:
- Progressive image loading
- Skeleton screens
- Optimistic UI updates
- Offline support (service workers)
**Memory leaks**:
- Clean up event listeners
- Cancel subscriptions
- Clear timers/intervals
- Abort pending requests on unmount
**Throttling & Debouncing**:
```javascript
// Debounce search input
const debouncedSearch = debounce(handleSearch, 300);
// Throttle scroll handler
const throttledScroll = throttle(handleScroll, 100);
```
## Testing Strategies
**Manual testing**:
- Test with extreme data (very long, very short, empty)
- Test in different languages
- Test offline
- Test slow connection (throttle to 3G)
- Test with screen reader
- Test keyboard-only navigation
- Test on old browsers
**Automated testing**:
- Unit tests for edge cases
- Integration tests for error scenarios
- E2E tests for critical paths
- Visual regression tests
- Accessibility tests (axe, WAVE)
**IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined.
**NEVER**:
- Assume perfect input (validate everything)
- Ignore internationalization (design for global)
- Leave error messages generic ("Error occurred")
- Forget offline scenarios
- Trust client-side validation alone
- Use fixed widths for text
- Assume English-length text
- Block entire interface when one component errors
## Verify Hardening
Test thoroughly with edge cases:
- **Long text**: Try names with 100+ characters
- **Emoji**: Use emoji in all text fields
- **RTL**: Test with Arabic or Hebrew
- **CJK**: Test with Chinese/Japanese/Korean
- **Network issues**: Disable internet, throttle connection
- **Large datasets**: Test with 1000+ items
- **Concurrent actions**: Click submit 10 times rapidly
- **Errors**: Force API errors, test all error states
- **Empty**: Remove all data, test empty states
Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
.blackbox/skills/i-normalize/SKILL.md
+62
View File
@@ -0,0 +1,62 @@
---
name: i-normalize
description: Normalize design to match your design system and ensure consistency
---
Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.
## Plan
Before making changes, deeply understand the context:
1. **Discover the design system**: Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
- Core design principles and aesthetic direction
- Target audience and personas
- Component patterns and conventions
- Design tokens (colors, typography, spacing)
**CRITICAL**: If something isn't clear, ask. Don't guess at design system principles.
2. **Analyze the current feature**: Assess what works and what doesn't:
- Where does it deviate from design system patterns?
- Which inconsistencies are cosmetic vs. functional?
- What's the root cause—missing tokens, one-off implementations, or conceptual misalignment?
3. **Create a normalization plan**: Define specific changes that will align the feature with the design system:
- Which components can be replaced with design system equivalents?
- Which styles need to use design tokens instead of hard-coded values?
- How can UX patterns match established user flows?
**IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.
## Execute
Systematically address all inconsistencies across these dimensions:
- **Typography**: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
- **Color & Theme**: Apply design system color tokens. Remove one-off color choices that break the palette.
- **Spacing & Layout**: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
- **Components**: Replace custom implementations with design system components. Ensure props and variants match established patterns.
- **Motion & Interaction**: Match animation timing, easing, and interaction patterns to other features.
- **Responsive Behavior**: Ensure breakpoints and responsive patterns align with design system standards.
- **Accessibility**: Verify contrast ratios, focus states, ARIA labels match design system requirements.
- **Progressive Disclosure**: Match information hierarchy and complexity management to established patterns.
**NEVER**:
- Create new one-off components when design system equivalents exist
- Hard-code values that should use design tokens
- Introduce new patterns that diverge from the design system
- Compromise accessibility for visual consistency
This is not an exhaustive list—apply judgment to identify all areas needing normalization.
## Clean Up
After normalization, ensure code quality:
- **Consolidate reusable components**: If you created new components that should be shared, move them to the design system or shared UI component path.
- **Remove orphaned code**: Delete unused implementations, styles, or files made obsolete by normalization.
- **Verify quality**: Lint, type-check, and test according to repository guidelines. Ensure normalization didn't introduce regressions.
- **Ensure DRYness**: Look for duplication introduced during refactoring and consolidate.
Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.
.blackbox/skills/i-onboard/SKILL.md
+237
View File
@@ -0,0 +1,237 @@
---
name: i-onboard
description: Design or improve onboarding flows, empty states, and first-time user experiences. Helps users get started successfully and understand value quickly.
---
Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
## Assess Onboarding Needs
Understand what users need to learn and why:
1. **Identify the challenge**:
- What are users trying to accomplish?
- What's confusing or unclear about current experience?
- Where do users get stuck or drop off?
- What's the "aha moment" we want users to reach?
2. **Understand the users**:
- What's their experience level? (Beginners, power users, mixed?)
- What's their motivation? (Excited and exploring? Required by work?)
- What's their time commitment? (5 minutes? 30 minutes?)
- What alternatives do they know? (Coming from competitor? New to category?)
3. **Define success**:
- What's the minimum users need to learn to be successful?
- What's the key action we want them to take? (First project? First invite?)
- How do we know onboarding worked? (Completion rate? Time to value?)
**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.
## Onboarding Principles
Follow these core principles:
### Show, Don't Tell
- Demonstrate with working examples, not just descriptions
- Provide real functionality in onboarding, not separate tutorial mode
- Use progressive disclosure - teach one thing at a time
### Make It Optional (When Possible)
- Let experienced users skip onboarding
- Don't block access to product
- Provide "Skip" or "I'll explore on my own" options
### Time to Value
- Get users to their "aha moment" ASAP
- Front-load most important concepts
- Teach 20% that delivers 80% of value
- Save advanced features for contextual discovery
### Context Over Ceremony
- Teach features when users need them, not upfront
- Empty states are onboarding opportunities
- Tooltips and hints at point of use
### Respect User Intelligence
- Don't patronize or over-explain
- Be concise and clear
- Assume users can figure out standard patterns
## Design Onboarding Experiences
Create appropriate onboarding for the context:
### Initial Product Onboarding
**Welcome Screen**:
- Clear value proposition (what is this product?)
- What users will learn/accomplish
- Time estimate (honest about commitment)
- Option to skip (for experienced users)
**Account Setup**:
- Minimal required information (collect more later)
- Explain why you're asking for each piece of information
- Smart defaults where possible
- Social login when appropriate
**Core Concept Introduction**:
- Introduce 1-3 core concepts (not everything)
- Use simple language and examples
- Interactive when possible (do, don't just read)
- Progress indication (step 1 of 3)
**First Success**:
- Guide users to accomplish something real
- Pre-populated examples or templates
- Celebrate completion (but don't overdo it)
- Clear next steps
### Feature Discovery & Adoption
**Empty States**:
Instead of blank space, show:
- What will appear here (description + screenshot/illustration)
- Why it's valuable
- Clear CTA to create first item
- Example or template option
Example:
```
No projects yet
Projects help you organize your work and collaborate with your team.
[Create your first project] or [Start from template]
```
**Contextual Tooltips**:
- Appear at relevant moment (first time user sees feature)
- Point directly at relevant UI element
- Brief explanation + benefit
- Dismissable (with "Don't show again" option)
- Optional "Learn more" link
**Feature Announcements**:
- Highlight new features when they're released
- Show what's new and why it matters
- Let users try immediately
- Dismissable
**Progressive Onboarding**:
- Teach features when users encounter them
- Badges or indicators on new/unused features
- Unlock complexity gradually (don't show all options immediately)
### Guided Tours & Walkthroughs
**When to use**:
- Complex interfaces with many features
- Significant changes to existing product
- Industry-specific tools needing domain knowledge
**How to design**:
- Spotlight specific UI elements (dim rest of page)
- Keep steps short (3-7 steps max per tour)
- Allow users to click through tour freely
- Include "Skip tour" option
- Make replayable (help menu)
**Best practices**:
- Interactive > passive (let users click real buttons)
- Focus on workflow, not features ("Create a project" not "This is the project button")
- Provide sample data so actions work
### Interactive Tutorials
**When to use**:
- Users need hands-on practice
- Concepts are complex or unfamiliar
- High stakes (better to practice in safe environment)
**How to design**:
- Sandbox environment with sample data
- Clear objectives ("Create a chart showing sales by region")
- Step-by-step guidance
- Validation (confirm they did it right)
- Graduation moment (you're ready!)
### Documentation & Help
**In-product help**:
- Contextual help links throughout interface
- Keyboard shortcut reference
- Search-able help center
- Video tutorials for complex workflows
**Help patterns**:
- `?` icon near complex features
- "Learn more" links in tooltips
- Keyboard shortcut hints (`⌘K` shown on search box)
## Empty State Design
Every empty state needs:
### What Will Be Here
"Your recent projects will appear here"
### Why It Matters
"Projects help you organize your work and collaborate with your team"
### How to Get Started
[Create project] or [Import from template]
### Visual Interest
Illustration or icon (not just text on blank page)
### Contextual Help
"Need help getting started? [Watch 2-min tutorial]"
**Empty state types**:
- **First use**: Never used this feature (emphasize value, provide template)
- **User cleared**: Intentionally deleted everything (light touch, easy to recreate)
- **No results**: Search or filter returned nothing (suggest different query, clear filters)
- **No permissions**: Can't access (explain why, how to get access)
- **Error state**: Failed to load (explain what happened, retry option)
## Implementation Patterns
### Technical approaches:
**Tooltip libraries**: Tippy.js, Popper.js
**Tour libraries**: Intro.js, Shepherd.js, React Joyride
**Modal patterns**: Focus trap, backdrop, ESC to close
**Progress tracking**: LocalStorage for "seen" states
**Analytics**: Track completion, drop-off points
**Storage patterns**:
```javascript
// Track which onboarding steps user has seen
localStorage.setItem('onboarding-completed', 'true');
localStorage.setItem('feature-tooltip-seen-reports', 'true');
```
**IMPORTANT**: Don't show same onboarding twice (annoying). Track completion and respect dismissals.
**NEVER**:
- Force users through long onboarding before they can use product
- Patronize users with obvious explanations
- Show same tooltip repeatedly (respect dismissals)
- Block all UI during tour (let users explore)
- Create separate tutorial mode disconnected from real product
- Overwhelm with information upfront (progressive disclosure!)
- Hide "Skip" or make it hard to find
- Forget about returning users (don't show initial onboarding again)
## Verify Onboarding Quality
Test with real users:
- **Time to completion**: Can users complete onboarding quickly?
- **Comprehension**: Do users understand after completing?
- **Action**: Do users take desired next step?
- **Skip rate**: Are too many users skipping? (Maybe it's too long/not valuable)
- **Completion rate**: Are users completing? (If low, simplify)
- **Time to value**: How long until users get first value?
Remember: You're a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.
.blackbox/skills/i-optimize/SKILL.md
+263
View File
@@ -0,0 +1,263 @@
---
name: i-optimize
description: Improve interface performance across loading speed, rendering, animations, images, and bundle size. Makes experiences faster and smoother.
---
Identify and fix performance issues to create faster, smoother user experiences.
## Assess Performance Issues
Understand current performance and identify problems:
1. **Measure current state**:
- **Core Web Vitals**: LCP, FID/INP, CLS scores
- **Load time**: Time to interactive, first contentful paint
- **Bundle size**: JavaScript, CSS, image sizes
- **Runtime performance**: Frame rate, memory usage, CPU usage
- **Network**: Request count, payload sizes, waterfall
2. **Identify bottlenecks**:
- What's slow? (Initial load? Interactions? Animations?)
- What's causing it? (Large images? Expensive JavaScript? Layout thrashing?)
- How bad is it? (Perceivable? Annoying? Blocking?)
- Who's affected? (All users? Mobile only? Slow connections?)
**CRITICAL**: Measure before and after. Premature optimization wastes time. Optimize what actually matters.
## Optimization Strategy
Create systematic improvement plan:
### Loading Performance
**Optimize Images**:
- Use modern formats (WebP, AVIF)
- Proper sizing (don't load 3000px image for 300px display)
- Lazy loading for below-fold images
- Responsive images (`srcset`, `picture` element)
- Compress images (80-85% quality is usually imperceptible)
- Use CDN for faster delivery
```html
<img
src="hero.webp"
srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px"
loading="lazy"
alt="Hero image"
/>
```
**Reduce JavaScript Bundle**:
- Code splitting (route-based, component-based)
- Tree shaking (remove unused code)
- Remove unused dependencies
- Lazy load non-critical code
- Use dynamic imports for large components
```javascript
// Lazy load heavy component
const HeavyChart = lazy(() => import('./HeavyChart'));
```
**Optimize CSS**:
- Remove unused CSS
- Critical CSS inline, rest async
- Minimize CSS files
- Use CSS containment for independent regions
**Optimize Fonts**:
- Use `font-display: swap` or `optional`
- Subset fonts (only characters you need)
- Preload critical fonts
- Use system fonts when appropriate
- Limit font weights loaded
```css
@font-face {
font-family: 'CustomFont';
src: url('/fonts/custom.woff2') format('woff2');
font-display: swap; /* Show fallback immediately */
unicode-range: U+0020-007F; /* Basic Latin only */
}
```
**Optimize Loading Strategy**:
- Critical resources first (async/defer non-critical)
- Preload critical assets
- Prefetch likely next pages
- Service worker for offline/caching
- HTTP/2 or HTTP/3 for multiplexing
### Rendering Performance
**Avoid Layout Thrashing**:
```javascript
// ❌ Bad: Alternating reads and writes (causes reflows)
elements.forEach(el => {
const height = el.offsetHeight; // Read (forces layout)
el.style.height = height * 2; // Write
});
// ✅ Good: Batch reads, then batch writes
const heights = elements.map(el => el.offsetHeight); // All reads
elements.forEach((el, i) => {
el.style.height = heights[i] * 2; // All writes
});
```
**Optimize Rendering**:
- Use CSS `contain` property for independent regions
- Minimize DOM depth (flatter is faster)
- Reduce DOM size (fewer elements)
- Use `content-visibility: auto` for long lists
- Virtual scrolling for very long lists (react-window, react-virtualized)
**Reduce Paint & Composite**:
- Use `transform` and `opacity` for animations (GPU-accelerated)
- Avoid animating layout properties (width, height, top, left)
- Use `will-change` sparingly for known expensive operations
- Minimize paint areas (smaller is faster)
### Animation Performance
**GPU Acceleration**:
```css
/* ✅ GPU-accelerated (fast) */
.animated {
transform: translateX(100px);
opacity: 0.5;
}
/* ❌ CPU-bound (slow) */
.animated {
left: 100px;
width: 300px;
}
```
**Smooth 60fps**:
- Target 16ms per frame (60fps)
- Use `requestAnimationFrame` for JS animations
- Debounce/throttle scroll handlers
- Use CSS animations when possible
- Avoid long-running JavaScript during animations
**Intersection Observer**:
```javascript
// Efficiently detect when elements enter viewport
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
// Element is visible, lazy load or animate
}
});
});
```
### React/Framework Optimization
**React-specific**:
- Use `memo()` for expensive components
- `useMemo()` and `useCallback()` for expensive computations
- Virtualize long lists
- Code split routes
- Avoid inline function creation in render
- Use React DevTools Profiler
**Framework-agnostic**:
- Minimize re-renders
- Debounce expensive operations
- Memoize computed values
- Lazy load routes and components
### Network Optimization
**Reduce Requests**:
- Combine small files
- Use SVG sprites for icons
- Inline small critical assets
- Remove unused third-party scripts
**Optimize APIs**:
- Use pagination (don't load everything)
- GraphQL to request only needed fields
- Response compression (gzip, brotli)
- HTTP caching headers
- CDN for static assets
**Optimize for Slow Connections**:
- Adaptive loading based on connection (navigator.connection)
- Optimistic UI updates
- Request prioritization
- Progressive enhancement
## Core Web Vitals Optimization
### Largest Contentful Paint (LCP < 2.5s)
- Optimize hero images
- Inline critical CSS
- Preload key resources
- Use CDN
- Server-side rendering
### First Input Delay (FID < 100ms) / INP (< 200ms)
- Break up long tasks
- Defer non-critical JavaScript
- Use web workers for heavy computation
- Reduce JavaScript execution time
### Cumulative Layout Shift (CLS < 0.1)
- Set dimensions on images and videos
- Don't inject content above existing content
- Use `aspect-ratio` CSS property
- Reserve space for ads/embeds
- Avoid animations that cause layout shifts
```css
/* Reserve space for image */
.image-container {
aspect-ratio: 16 / 9;
}
```
## Performance Monitoring
**Tools to use**:
- Chrome DevTools (Lighthouse, Performance panel)
- WebPageTest
- Core Web Vitals (Chrome UX Report)
- Bundle analyzers (webpack-bundle-analyzer)
- Performance monitoring (Sentry, DataDog, New Relic)
**Key metrics**:
- LCP, FID/INP, CLS (Core Web Vitals)
- Time to Interactive (TTI)
- First Contentful Paint (FCP)
- Total Blocking Time (TBT)
- Bundle size
- Request count
**IMPORTANT**: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative.
**NEVER**:
- Optimize without measuring (premature optimization)
- Sacrifice accessibility for performance
- Break functionality while optimizing
- Use `will-change` everywhere (creates new layers, uses memory)
- Lazy load above-fold content
- Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)
- Forget about mobile performance (often slower devices, slower connections)
## Verify Improvements
Test that optimizations worked:
- **Before/after metrics**: Compare Lighthouse scores
- **Real user monitoring**: Track improvements for real users
- **Different devices**: Test on low-end Android, not just flagship iPhone
- **Slow connections**: Throttle to 3G, test experience
- **No regressions**: Ensure functionality still works
- **User perception**: Does it *feel* faster?
Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
.blackbox/skills/i-polish/SKILL.md
+196
View File
@@ -0,0 +1,196 @@
---
name: i-polish
description: Final quality pass before shipping. Fixes alignment, spacing, consistency, and detail issues that separate good from great.
---
**First**: Use the i-frontend-design skill for design principles and anti-patterns.
Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
## Pre-Polish Assessment
Understand the current state and goals:
1. **Review completeness**:
- Is it functionally complete?
- Are there known issues to preserve (mark with TODOs)?
- What's the quality bar? (MVP vs flagship feature?)
- When does it ship? (How much time for polish?)
2. **Identify polish areas**:
- Visual inconsistencies
- Spacing and alignment issues
- Interaction state gaps
- Copy inconsistencies
- Edge cases and error states
- Loading and transition smoothness
**CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
## Polish Systematically
Work through these dimensions methodically:
### Visual Alignment & Spacing
- **Pixel-perfect alignment**: Everything lines up to grid
- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)
- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)
- **Responsive consistency**: Spacing and alignment work at all breakpoints
- **Grid adherence**: Elements snap to baseline grid
**Check**:
- Enable grid overlay and verify alignment
- Check spacing with browser inspector
- Test at multiple viewport sizes
- Look for elements that "feel" off
### Typography Refinement
- **Hierarchy consistency**: Same elements use same sizes/weights throughout
- **Line length**: 45-75 characters for body text
- **Line height**: Appropriate for font size and context
- **Widows & orphans**: No single words on last line
- **Hyphenation**: Appropriate for language and column width
- **Kerning**: Adjust letter spacing where needed (especially headlines)
- **Font loading**: No FOUT/FOIT flashes
### Color & Contrast
- **Contrast ratios**: All text meets WCAG standards
- **Consistent token usage**: No hard-coded colors, all use design tokens
- **Theme consistency**: Works in all theme variants
- **Color meaning**: Same colors mean same things throughout
- **Accessible focus**: Focus indicators visible with sufficient contrast
- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)
- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency
### Interaction States
Every interactive element needs all states:
- **Default**: Resting state
- **Hover**: Subtle feedback (color, scale, shadow)
- **Focus**: Keyboard focus indicator (never remove without replacement)
- **Active**: Click/tap feedback
- **Disabled**: Clearly non-interactive
- **Loading**: Async action feedback
- **Error**: Validation or error state
- **Success**: Successful completion
**Missing states create confusion and broken experiences**.
### Micro-interactions & Transitions
- **Smooth transitions**: All state changes animated appropriately (150-300ms)
- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
- **No jank**: 60fps animations, only animate transform and opacity
- **Appropriate motion**: Motion serves purpose, not decoration
- **Reduced motion**: Respects `prefers-reduced-motion`
### Content & Copy
- **Consistent terminology**: Same things called same names throughout
- **Consistent capitalization**: Title Case vs Sentence case applied consistently
- **Grammar & spelling**: No typos
- **Appropriate length**: Not too wordy, not too terse
- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
### Icons & Images
- **Consistent style**: All icons from same family or matching style
- **Appropriate sizing**: Icons sized consistently for context
- **Proper alignment**: Icons align with adjacent text optically
- **Alt text**: All images have descriptive alt text
- **Loading states**: Images don't cause layout shift, proper aspect ratios
- **Retina support**: 2x assets for high-DPI screens
### Forms & Inputs
- **Label consistency**: All inputs properly labeled
- **Required indicators**: Clear and consistent
- **Error messages**: Helpful and consistent
- **Tab order**: Logical keyboard navigation
- **Auto-focus**: Appropriate (don't overuse)
- **Validation timing**: Consistent (on blur vs on submit)
### Edge Cases & Error States
- **Loading states**: All async actions have loading feedback
- **Empty states**: Helpful empty states, not just blank space
- **Error states**: Clear error messages with recovery paths
- **Success states**: Confirmation of successful actions
- **Long content**: Handles very long names, descriptions, etc.
- **No content**: Handles missing data gracefully
- **Offline**: Appropriate offline handling (if applicable)
### Responsiveness
- **All breakpoints**: Test mobile, tablet, desktop
- **Touch targets**: 44x44px minimum on touch devices
- **Readable text**: No text smaller than 14px on mobile
- **No horizontal scroll**: Content fits viewport
- **Appropriate reflow**: Content adapts logically
### Performance
- **Fast initial load**: Optimize critical path
- **No layout shift**: Elements don't jump after load (CLS)
- **Smooth interactions**: No lag or jank
- **Optimized images**: Appropriate formats and sizes
- **Lazy loading**: Off-screen content loads lazily
### Code Quality
- **Remove console logs**: No debug logging in production
- **Remove commented code**: Clean up dead code
- **Remove unused imports**: Clean up unused dependencies
- **Consistent naming**: Variables and functions follow conventions
- **Type safety**: No TypeScript `any` or ignored errors
- **Accessibility**: Proper ARIA labels and semantic HTML
## Polish Checklist
Go through systematically:
- [ ] Visual alignment perfect at all breakpoints
- [ ] Spacing uses design tokens consistently
- [ ] Typography hierarchy consistent
- [ ] All interactive states implemented
- [ ] All transitions smooth (60fps)
- [ ] Copy is consistent and polished
- [ ] Icons are consistent and properly sized
- [ ] All forms properly labeled and validated
- [ ] Error states are helpful
- [ ] Loading states are clear
- [ ] Empty states are welcoming
- [ ] Touch targets are 44x44px minimum
- [ ] Contrast ratios meet WCAG AA
- [ ] Keyboard navigation works
- [ ] Focus indicators visible
- [ ] No console errors or warnings
- [ ] No layout shift on load
- [ ] Works in all supported browsers
- [ ] Respects reduced motion preference
- [ ] Code is clean (no TODOs, console.logs, commented code)
**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
**NEVER**:
- Polish before it's functionally complete
- Spend hours on polish if it ships in 30 minutes (triage)
- Introduce bugs while polishing (test thoroughly)
- Ignore systematic issues (if spacing is off everywhere, fix the system)
- Perfect one thing while leaving others rough (consistent quality level)
## Final Verification
Before marking as done:
- **Use it yourself**: Actually interact with the feature
- **Test on real devices**: Not just browser DevTools
- **Ask someone else to review**: Fresh eyes catch things
- **Compare to design**: Match intended design
- **Check all states**: Don't just test happy path
Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.
.blackbox/skills/i-quieter/SKILL.md
+113
View File
@@ -0,0 +1,113 @@
---
name: i-quieter
description: Tone down overly bold or visually aggressive designs. Reduces intensity while maintaining design quality and impact.
---
Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
## MANDATORY PREPARATION
### Context Gathering (Do This First)
You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well.
Attempt to gather these from the current thread or codebase.
1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and ask the user directly to clarify what you cannot infer. whether you got it right.
2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST ask the user directly to clarify what you cannot infer. clarifying questions first to complete your context.
Do NOT proceed until you have answers. Guessing leads to generic design.
### Use frontend-design skill
Use the i-frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
---
## Assess Current State
Analyze what makes the design feel too intense:
1. **Identify intensity sources**:
- **Color saturation**: Overly bright or saturated colors
- **Contrast extremes**: Too much high-contrast juxtaposition
- **Visual weight**: Too many bold, heavy elements competing
- **Animation excess**: Too much motion or overly dramatic effects
- **Complexity**: Too many visual elements, patterns, or decorations
- **Scale**: Everything is large and loud with no hierarchy
2. **Understand the context**:
- What's the purpose? (Marketing vs tool vs reading experience)
- Who's the audience? (Some contexts need energy)
- What's working? (Don't throw away good ideas)
- What's the core message? (Preserve what matters)
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
**CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
## Plan Refinement
Create a strategy to reduce intensity while maintaining impact:
- **Color approach**: Desaturate or shift to more sophisticated tones?
- **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
- **Simplification approach**: What can be removed entirely?
- **Sophistication approach**: How can we signal quality through restraint?
**IMPORTANT**: Great quiet design is harder than great bold design. Subtlety requires precision.
## Refine the Design
Systematically reduce intensity across these dimensions:
### Color Refinement
- **Reduce saturation**: Shift from fully saturated to 70-85% saturation
- **Soften palette**: Replace bright colors with muted, sophisticated tones
- **Reduce color variety**: Use fewer colors more thoughtfully
- **Neutral dominance**: Let neutrals do more work, use color as accent (10% rule)
- **Gentler contrasts**: High contrast only where it matters most
- **Tinted grays**: Use warm or cool tinted grays instead of pure gray—adds sophistication without loudness
- **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead
### Visual Weight Reduction
- **Typography**: Reduce font weights (900 → 600, 700 → 500), decrease sizes where appropriate
- **Hierarchy through subtlety**: Use weight, size, and space instead of color and boldness
- **White space**: Increase breathing room, reduce density
- **Borders & lines**: Reduce thickness, decrease opacity, or remove entirely
### Simplification
- **Remove decorative elements**: Gradients, shadows, patterns, textures that don't serve purpose
- **Simplify shapes**: Reduce border radius extremes, simplify custom shapes
- **Reduce layering**: Flatten visual hierarchy where possible
- **Clean up effects**: Reduce or remove blur effects, glows, multiple shadows
### Motion Reduction
- **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing
- **Remove decorative animations**: Keep functional motion, remove flourishes
- **Subtle micro-interactions**: Replace dramatic effects with gentle feedback
- **Refined easing**: Use ease-out-quart for smooth, understated motion—never bounce or elastic
- **Remove animations entirely** if they're not serving a clear purpose
### Composition Refinement
- **Reduce scale jumps**: Smaller contrast between sizes creates calmer feeling
- **Align to grid**: Bring rogue elements back into systematic alignment
- **Even out spacing**: Replace extreme spacing variations with consistent rhythm
**NEVER**:
- Make everything the same size/weight (hierarchy still matters)
- Remove all color (quiet ≠ grayscale)
- Eliminate all personality (maintain character through refinement)
- Sacrifice usability for aesthetics (functional elements still need clear affordances)
- Make everything small and light (some anchors needed)
## Verify Quality
Ensure refinement maintains quality:
- **Still functional**: Can users still accomplish tasks easily?
- **Still distinctive**: Does it have character, or is it generic now?
- **Better reading**: Is text easier to read for extended periods?
- **Sophistication**: Does it feel more refined and premium?
Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.
.blackbox/skills/i-teach-impeccable/SKILL.md
+68
View File
@@ -0,0 +1,68 @@
---
name: i-teach-impeccable
description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.
---
Gather design context for this project, then persist it for all future sessions.
## Step 1: Explore the Codebase
Before asking questions, thoroughly scan the project to discover what you can:
- **README and docs**: Project purpose, target audience, any stated goals
- **Package.json / config files**: Tech stack, dependencies, existing design libraries
- **Existing components**: Current design patterns, spacing, typography in use
- **Brand assets**: Logos, favicons, color values already defined
- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
- **Any style guides or brand documentation**
Note what you've learned and what remains unclear.
## Step 2: Ask UX-Focused Questions
ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
### Users & Purpose
- Who uses this? What's their context when using it?
- What job are they trying to get done?
- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
### Brand & Personality
- How would you describe the brand personality in 3 words?
- Any reference sites or apps that capture the right feel? What specifically about them?
- What should this explicitly NOT look like? Any anti-references?
### Aesthetic Preferences
- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
- Light mode, dark mode, or both?
- Any colors that must be used or avoided?
### Accessibility & Inclusion
- Specific accessibility requirements? (WCAG level, known user needs)
- Considerations for reduced motion, color blindness, or other accommodations?
Skip questions where the answer is already clear from the codebase exploration.
## Step 3: Write Design Context
Synthesize your findings and the user's answers into a `## Design Context` section:
```markdown
## Design Context
### Users
[Who they are, their context, the job to be done]
### Brand Personality
[Voice, tone, 3-word personality, emotional goals]
### Aesthetic Direction
[Visual tone, references, anti-references, theme]
### Design Principles
[3-5 principles derived from the conversation that should guide all design decisions]
```
Write this section to AGENTS.md in the project root. If the file exists, append or update the Design Context section.
Confirm completion and summarize the key design principles that will now guide all future work.
.blackbox/skills/openai-docs/LICENSE.txt
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf of
any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don\'t include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.blackbox/skills/openai-docs/SKILL.md
+56
View File
@@ -0,0 +1,56 @@
---
name: "openai-docs"
description: "Use when the user asks how to build with OpenAI products or APIs and needs up-to-date official documentation with citations (for example: Codex, Responses API, Chat Completions, Apps SDK, Agents SDK, Realtime, model capabilities or limits); prioritize OpenAI docs MCP tools and restrict any fallback browsing to official OpenAI domains."
---
# OpenAI Docs
Provide authoritative, current guidance from OpenAI developer docs using the developers.openai.com MCP server. Always prioritize the developer docs MCP tools over web.run for OpenAI-related questions. Only if the MCP server is installed and returns no meaningful results should you fall back to web search.
## Quick start
- Use `mcp__openaiDeveloperDocs__search_openai_docs` to find the most relevant doc pages.
- Use `mcp__openaiDeveloperDocs__fetch_openai_doc` to pull exact sections and quote/paraphrase accurately.
- Use `mcp__openaiDeveloperDocs__list_openai_docs` only when you need to browse or discover pages without a clear query.
## OpenAI product snapshots
1. Apps SDK: Build ChatGPT apps by providing a web component UI and an MCP server that exposes your app's tools to ChatGPT.
2. Responses API: A unified endpoint designed for stateful, multimodal, tool-using interactions in agentic workflows.
3. Chat Completions API: Generate a model response from a list of messages comprising a conversation.
4. Codex: OpenAI's coding agent for software development that can write, understand, review, and debug code.
5. gpt-oss: Open-weight OpenAI reasoning models (gpt-oss-120b and gpt-oss-20b) released under the Apache 2.0 license.
6. Realtime API: Build low-latency, multimodal experiences including natural speech-to-speech conversations.
7. Agents SDK: A toolkit for building agentic apps where a model can use tools and context, hand off to other agents, stream partial results, and keep a full trace.
## If MCP server is missing
If MCP tools fail or no OpenAI docs resources are available:
1. Run the install command yourself: `codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp`
2. If it fails due to permissions/sandboxing, immediately retry the same command with escalated permissions and include a 1-sentence justification for approval. Do not ask the user to run it yet.
3. Only if the escalated attempt fails, ask the user to run the install command.
4. Ask the user to restart Codex.
5. Re-run the doc search/fetch after restart.
## Workflow
1. Clarify the product scope (Codex, OpenAI API, or ChatGPT Apps SDK) and the task.
2. Search docs with a precise query.
3. Fetch the best page and the specific section needed (use `anchor` when possible).
4. Answer with concise guidance and cite the doc source.
5. Provide code snippets only when the docs support them.
## Quality rules
- Treat OpenAI docs as the source of truth; avoid speculation.
- Keep quotes short and within policy limits; prefer paraphrase with citations.
- If multiple pages differ, call out the difference and cite both.
- If docs do not cover the user’s need, say so and offer next steps.
## Tooling notes
- Always use MCP doc tools before any web search for OpenAI-related questions.
- If the MCP server is installed but returns no meaningful results, then use web search as a fallback.
- When falling back to web search, restrict to official OpenAI domains (developers.openai.com, platform.openai.com) and cite sources.
.blackbox/skills/openai-docs/agents/openai.yaml
+14
View File
@@ -0,0 +1,14 @@
interface:
display_name: "OpenAI Docs"
short_description: "Reference the official OpenAI Developer docs"
icon_small: "./assets/openai-small.svg"
icon_large: "./assets/openai.png"
default_prompt: "Look up official OpenAI docs for this task and answer with concise, cited guidance."
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs"
description: "OpenAI Developer Docs MCP server"
transport: "streamable_http"
url: "https://developers.openai.com/mcp"
.blackbox/skills/openai-docs/assets/openai-small.svg
+3
View File
@@ -0,0 +1,3 @@
<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" fill="currentColor" viewBox="0 0 14 14">
<path d="M10.931 3.34a.112.112 0 0 0-.069-.104l-.038-.007c-1.537.05-2.45.318-3.714 1.002v6.683c.48-.248.936-.44 1.414-.58.695-.203 1.417-.292 2.303-.305l.038-.008a.113.113 0 0 0 .066-.104V3.341ZM2.363 9.919c0 .064.051.11.105.111l.33.008c1.162.046 2.042.243 2.975.662-.403-.585-1.008-1.075-1.654-1.292a.991.991 0 0 1-.674-.941v-5.14a6.36 6.36 0 0 0-.59-.076l-.37-.02a.115.115 0 0 0-.122.111v6.577Zm9.455-.001a.998.998 0 0 1-.877.992l-.101.007c-.832.012-1.47.095-2.066.27-.599.174-1.176.448-1.883.863a.444.444 0 0 1-.449 0c-1.299-.763-2.229-1.07-3.689-1.125l-.299-.008a.997.997 0 0 1-.977-.998V3.342c0-.573.478-1.017 1.038-.999l.417.023c.188.015.35.037.513.062v-.754c0-.708.749-1.244 1.429-.903.984.492 1.836 1.449 2.15 2.505 1.216-.617 2.222-.884 3.771-.934l.105.003a.998.998 0 0 1 .918.996v6.576ZM4.332 8.466c0 .049.03.087.07.1l.24.091a4.319 4.319 0 0 1 1.581 1.176V3.721c-.164-.803-.799-1.617-1.584-2.07l-.162-.088c-.025-.012-.054-.013-.088.009a.12.12 0 0 0-.057.102v6.792Z"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

.blackbox/skills/openai-docs/assets/openai.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

.blackbox/skills/playwright-interactive/LICENSE.txt
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright (c) Microsoft Corporation.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.blackbox/skills/playwright-interactive/NOTICE.txt
+13
View File
@@ -0,0 +1,13 @@
This skill reuses the Playwright icon assets from `.codex/skills/playwright/assets/`.
The local `playwright` skill attributes those assets to the Microsoft
`playwright-cli` repository.
Copyright (c) Microsoft Corporation.
Licensed under the Apache License, Version 2.0.
See LICENSE.txt in this directory.
Modifications:
- Repackaged the existing repository Playwright assets for this `js_repl`-focused skill.
- Wrote new skill instructions for persistent browser debugging.
.blackbox/skills/playwright-interactive/SKILL.md
+689
View File
@@ -0,0 +1,689 @@
---
name: "playwright-interactive"
description: "Persistent browser and Electron interaction through `js_repl` for fast iterative UI debugging."
---
# Playwright Interactive Skill
Use a persistent `js_repl` Playwright session to debug local web or Electron apps, keep the same handles alive across iterations, and run functional plus visual QA without restarting the whole toolchain unless the process ownership changed.
## Preconditions
- `js_repl` must be enabled for this skill.
- If `js_repl` is missing, enable it in `~/.codex/config.toml`:
```toml
[features]
js_repl = true
```
- You can also start a new session with `--enable js_repl` (equivalent to `-c features.js_repl=true`).
- After enabling `js_repl`, start a new Codex session so the tool list refreshes.
- For now, run this workflow with sandboxing disabled: start Codex with `--sandbox danger-full-access` (or the equivalent config for `sandbox_mode=danger-full-access`). This is a temporary requirement while `js_repl` + Playwright support inside the sandbox is still being completed.
- Run setup from the same project directory you need to debug.
- Treat `js_repl_reset` as a recovery tool, not routine cleanup. Resetting the kernel destroys your Playwright handles.
## One-time setup
```bash
test -f package.json || npm init -y
npm install playwright
# Web-only, for headed Chromium or mobile emulation:
# npx playwright install chromium
# Electron-only, and only if the target workspace is the app itself:
# npm install --save-dev electron
node -e "import('playwright').then(() => console.log('playwright import ok')).catch((error) => { console.error(error); process.exit(1); })"
```
If you switch to a different workspace later, repeat setup there.
## Core Workflow
1. Write a brief QA inventory before testing:
- Build the inventory from three sources: the user's requested requirements, the user-visible features or behaviors you actually implemented, and the claims you expect to make in the final response.
- Anything that appears in any of those three sources must map to at least one QA check before signoff.
- List the user-visible claims you intend to sign off on.
- List every meaningful user-facing control, mode switch, or implemented interactive behavior.
- List the state changes or view changes each control or implemented behavior can cause.
- Use this as the shared coverage list for both functional QA and visual QA.
- For each claim or control-state pair, note the intended functional check, the specific state where the visual check must happen, and the evidence you expect to capture.
- If a requirement is visually central but subjective, convert it into an observable QA check instead of leaving it implicit.
- Add at least 2 exploratory or off-happy-path scenarios that could expose fragile behavior.
2. Run the bootstrap cell once.
3. Start or confirm any required dev server in a persistent TTY session.
4. Launch the correct runtime and keep reusing the same Playwright handles.
5. After each code change, reload for renderer-only changes or relaunch for main-process/startup changes.
6. Run functional QA with normal user input.
7. Run a separate visual QA pass.
8. Verify viewport fit and capture the screenshots needed to support your claims.
9. Clean up the Playwright session only when the task is actually finished.
## Bootstrap (Run Once)
```javascript
var chromium;
var electronLauncher;
var browser;
var context;
var page;
var mobileContext;
var mobilePage;
var electronApp;
var appWindow;
try {
({ chromium, _electron: electronLauncher } = await import("playwright"));
console.log("Playwright loaded");
} catch (error) {
throw new Error(
`Could not load playwright from the current js_repl cwd. Run the setup commands from this workspace first. Original error: ${error}`
);
}
```
Binding rules:
- Use `var` for the shared top-level Playwright handles because later `js_repl` cells reuse them.
- The setup cells below are intentionally short happy paths. If a handle looks stale, set that binding to `undefined` and rerun the cell instead of adding recovery logic everywhere.
- Prefer one named handle per surface you care about (`page`, `mobilePage`, `appWindow`) over repeatedly rediscovering pages from the context.
Shared web helpers:
```javascript
var resetWebHandles = function () {
context = undefined;
page = undefined;
mobileContext = undefined;
mobilePage = undefined;
};
var ensureWebBrowser = async function () {
if (browser && !browser.isConnected()) {
browser = undefined;
resetWebHandles();
}
browser ??= await chromium.launch({ headless: false });
return browser;
};
var reloadWebContexts = async function () {
for (const currentContext of [context, mobileContext]) {
if (!currentContext) continue;
for (const p of currentContext.pages()) {
await p.reload({ waitUntil: "domcontentloaded" });
}
}
console.log("Reloaded existing web tabs");
};
```
## Choose Session Mode
For web apps, use an explicit viewport by default and treat native-window mode as a separate validation pass.
- Use an explicit viewport for routine iteration, breakpoint checks, reproducible screenshots, snapshot diffs, and model-assisted localization. This is the default because it is stable across machines and avoids host window-manager variability.
- When you need deterministic high-DPI behavior, keep the explicit viewport and add `deviceScaleFactor` rather than switching straight to native-window mode.
- Use native-window mode (`viewport: null`) for a separate headed pass when you need to validate launched window size, OS-level DPI behavior, browser chrome interactions, or bugs that may depend on the host display configuration.
- For Electron, assume native-window behavior all the time. Electron launches through Playwright with `noDefaultViewport`, so treat it like a real desktop window and check the as-launched size and layout before resizing anything.
- When signoff depends on both layout breakpoints and real desktop behavior, do both passes: explicit viewport first for deterministic QA, then native-window validation for final environment-specific checks.
- Treat switching modes as a context reset. Do not reuse a viewport-emulated `context` for a native-window pass or vice versa; close the old `page` and `context`, then create a new one for the new mode.
## Start or Reuse Web Session
Desktop and mobile web sessions share the same `browser`, helpers, and QA flow. The main difference is which context and page pair you create.
### Desktop Web Context
Set `TARGET_URL` to the app you are debugging. For local servers, prefer `127.0.0.1` over `localhost`.
```javascript
var TARGET_URL = "http://127.0.0.1:3000";
if (page?.isClosed()) page = undefined;
await ensureWebBrowser();
context ??= await browser.newContext({
viewport: { width: 1600, height: 900 },
});
page ??= await context.newPage();
await page.goto(TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded:", await page.title());
```
If `context` or `page` is stale, set `context = page = undefined` and rerun the cell.
### Mobile Web Context
Reuse `TARGET_URL` when it already exists; otherwise set a mobile target directly.
```javascript
var MOBILE_TARGET_URL = typeof TARGET_URL === "string"
? TARGET_URL
: "http://127.0.0.1:3000";
if (mobilePage?.isClosed()) mobilePage = undefined;
await ensureWebBrowser();
mobileContext ??= await browser.newContext({
viewport: { width: 390, height: 844 },
isMobile: true,
hasTouch: true,
});
mobilePage ??= await mobileContext.newPage();
await mobilePage.goto(MOBILE_TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded mobile:", await mobilePage.title());
```
If `mobileContext` or `mobilePage` is stale, set `mobileContext = mobilePage = undefined` and rerun the cell.
### Native-Window Web Pass
```javascript
var TARGET_URL = "http://127.0.0.1:3000";
await ensureWebBrowser();
await page?.close().catch(() => {});
await context?.close().catch(() => {});
page = undefined;
context = undefined;
browser ??= await chromium.launch({ headless: false });
context = await browser.newContext({ viewport: null });
page = await context.newPage();
await page.goto(TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded native window:", await page.title());
```
## Start or Reuse Electron Session
Set `ELECTRON_ENTRY` to `.` when the current workspace is the Electron app and `package.json` points `main` to the right entry file. If you need to target a specific main-process file directly, use a path such as `./main.js` instead.
```javascript
var ELECTRON_ENTRY = ".";
if (appWindow?.isClosed()) appWindow = undefined;
if (!appWindow && electronApp) {
await electronApp.close().catch(() => {});
electronApp = undefined;
}
electronApp ??= await electronLauncher.launch({
args: [ELECTRON_ENTRY],
});
appWindow ??= await electronApp.firstWindow();
console.log("Loaded Electron window:", await appWindow.title());
```
If `js_repl` is not already running from the Electron app workspace, pass `cwd` explicitly when launching.
If the app process looks stale, set `electronApp = appWindow = undefined` and rerun the cell.
If you already have an Electron session but need a fresh process after a main-process, preload, or startup change, use the restart cell in the next section instead of rerunning this one.
## Reuse Sessions During Iteration
Keep the same session alive whenever you can.
Web renderer reload:
```javascript
await reloadWebContexts();
```
Electron renderer-only reload:
```javascript
await appWindow.reload({ waitUntil: "domcontentloaded" });
console.log("Reloaded Electron window");
```
Electron restart after main-process, preload, or startup changes:
```javascript
await electronApp.close().catch(() => {});
electronApp = undefined;
appWindow = undefined;
electronApp = await electronLauncher.launch({
args: [ELECTRON_ENTRY],
});
appWindow = await electronApp.firstWindow();
console.log("Relaunched Electron window:", await appWindow.title());
```
If your launch requires an explicit `cwd`, include the same `cwd` here.
Default posture:
- Keep each `js_repl` cell short and focused on one interaction burst.
- Reuse the existing top-level bindings (`browser`, `context`, `page`, `electronApp`, `appWindow`) instead of redeclaring them.
- If you need isolation, create a new page or a new context inside the same browser.
- For Electron, use `electronApp.evaluate(...)` only for main-process inspection or purpose-built diagnostics.
- Fix helper mistakes in place; do not reset the REPL unless the kernel is actually broken.
## Checklists
### Session Loop
- Bootstrap `js_repl` once, then keep the same Playwright handles alive across iterations.
- Launch the target runtime from the current workspace.
- Make the code change.
- Reload or relaunch using the correct path for that change.
- Update the shared QA inventory if exploration reveals an additional control, state, or visible claim.
- Re-run functional QA.
- Re-run visual QA.
- Capture final artifacts only after the current state is the one you are evaluating.
### Reload Decision
- Renderer-only change: reload the existing page or Electron window.
- Main-process, preload, or startup change: relaunch Electron.
- New uncertainty about process ownership or startup code: relaunch instead of guessing.
### Functional QA
- Use real user controls for signoff: keyboard, mouse, click, touch, or equivalent Playwright input APIs.
- Verify at least one end-to-end critical flow.
- Confirm the visible result of that flow, not just internal state.
- For realtime or animation-heavy apps, verify behavior under actual interaction timing.
- Work through the shared QA inventory rather than ad hoc spot checks.
- Cover every obvious visible control at least once before signoff, not only the main happy path.
- For reversible controls or stateful toggles in the inventory, test the full cycle: initial state, changed state, and return to the initial state.
- After the scripted checks pass, do a short exploratory pass using normal input for 30-90 seconds instead of following only the intended path.
- If the exploratory pass reveals a new state, control, or claim, add it to the shared QA inventory and cover it before signoff.
- `page.evaluate(...)` and `electronApp.evaluate(...)` may inspect or stage state, but they do not count as signoff input.
### Visual QA
- Treat visual QA as separate from functional QA.
- Use the same shared QA inventory defined before testing and updated during QA; do not start visual coverage from a different implicit list.
- Restate the user-visible claims and verify each one explicitly; do not assume a functional pass proves a visual claim.
- A user-visible claim is not signed off until it has been inspected in the specific state where it is meant to be perceived.
- Inspect the initial viewport before scrolling.
- Confirm that the initial view visibly supports the interface's primary claims; if a core promised element is not clearly perceptible there, treat that as a bug.
- Inspect all required visible regions, not just the main interaction surface.
- Inspect the states and modes already enumerated in the shared QA inventory, including at least one meaningful post-interaction state when the task is interactive.
- If motion or transitions are part of the experience, inspect at least one in-transition state in addition to the settled endpoints.
- If labels, overlays, annotations, guides, or highlights are meant to track changing content, verify that relationship after the relevant state change.
- For dynamic or interaction-dependent visuals, inspect long enough to judge stability, layering, and readability; do not rely on a single screenshot for signoff.
- For interfaces that can become denser after loading or interaction, inspect the densest realistic state you can reach during QA, not only the empty, loading, or collapsed state.
- If the product has a defined minimum supported viewport or window size, run a separate visual QA pass there; otherwise, choose a smaller but still realistic size and inspect it explicitly.
- Distinguish presence from implementation: if an intended affordance is technically there but not clearly perceptible because of weak contrast, occlusion, clipping, or instability, treat that as a visual failure.
- If any required visible region is clipped, cut off, obscured, or pushed outside the viewport in the state you are evaluating, treat that as a bug even if page-level scroll metrics appear acceptable.
- Look for clipping, overflow, distortion, layout imbalance, inconsistent spacing, alignment problems, illegible text, weak contrast, broken layering, and awkward motion states.
- Judge aesthetic quality as well as correctness. The UI should feel intentional, coherent, and visually pleasing for the task.
- Prefer viewport screenshots for signoff. Use full-page captures only as secondary debugging artifacts, and capture a focused screenshot when a region needs closer inspection.
- If motion makes a screenshot ambiguous, wait briefly for the UI to settle, then capture the image you are actually evaluating.
- Before signoff, explicitly ask: what visible part of this interface have I not yet inspected closely?
- Before signoff, explicitly ask: what visible defect would most likely embarrass this result if the user looked closely?
### Signoff
- The functional path passed with normal user input.
- Coverage is explicit against the shared QA inventory: note which requirements, implemented features, controls, states, and claims were exercised, and call out any intentional exclusions.
- The visual QA pass covered the whole relevant interface.
- Each user-visible claim has a matching visual check and reviewed screenshot artifact from the state and viewport or window size where that claim matters.
- The viewport-fit checks passed for the intended initial view and any required minimum supported viewport or window size.
- If the product launches in a window, the as-launched size, placement, and initial layout were checked before any manual resize or repositioning.
- The UI is not just functional; it is visually coherent and not aesthetically weak for the task.
- Functional correctness, viewport fit, and visual quality must each pass on their own; one does not imply the others.
- A short exploratory pass was completed for interactive products, and the response mentions what that pass covered.
- If screenshot review and numeric checks disagreed at any point, the discrepancy was investigated before signoff; visible clipping in screenshots is a failure to resolve, not something metrics can overrule.
- Include a brief negative confirmation of the main defect classes you checked for and did not find.
- Cleanup was executed, or you intentionally kept the session alive for further work.
## Screenshot Examples
If you plan to emit a screenshot through `codex.emitImage(...)`, use the CSS-normalized paths in the next section by default. Those are the canonical examples for screenshots that will be interpreted by the model or used for coordinate-based follow-up actions. Keep raw captures as an exception for fidelity-sensitive debugging only; the raw exception examples appear after the normalization guidance.
### Model-bound screenshots (default)
If you will emit a screenshot with `codex.emitImage(...)` for model interpretation, normalize it to CSS pixels for the exact region you captured before emitting. This keeps returned coordinates aligned with Playwright CSS pixels if the reply is later used for clicking, and it also reduces image payload size and model token cost.
Do not emit raw native-window screenshots by default. Skip normalization only when you explicitly need device-pixel fidelity, such as Retina or DPI artifact debugging, pixel-accurate rendering inspection, or another fidelity-sensitive case where raw pixels matter more than payload size. For local-only inspection that will not be emitted to the model, raw capture is fine.
Do not assume `page.screenshot({ scale: "css" })` is enough in native-window mode (`viewport: null`). In Chromium on macOS Retina displays, headed native-window screenshots can still come back at device-pixel size even when `scale: "css"` is requested. The same caveat applies to Electron windows launched through Playwright because Electron runs with `noDefaultViewport`, and `appWindow.screenshot({ scale: "css" })` may still return device-pixel output.
Use separate normalization paths for web pages and Electron windows:
- Web: prefer `page.screenshot({ scale: "css" })` directly. If native-window Chromium still returns device-pixel output, resize inside the current page with canvas; no scratch page is required.
- Electron: do not use `appWindow.context().newPage()` or `electronApp.context().newPage()` as a scratch page. Electron contexts do not support that path reliably. Capture in the main process with `BrowserWindow.capturePage(...)`, resize with `nativeImage.resize(...)`, and emit those bytes directly.
Shared helpers and conventions:
```javascript
var emitJpeg = async function (bytes) {
await codex.emitImage({
bytes,
mimeType: "image/jpeg",
});
};
var emitWebJpeg = async function (surface, options = {}) {
await emitJpeg(await surface.screenshot({
type: "jpeg",
quality: 85,
scale: "css",
...options,
}));
};
var clickCssPoint = async function ({ surface, x, y, clip }) {
await surface.mouse.click(
clip ? clip.x + x : x,
clip ? clip.y + y : y
);
};
var tapCssPoint = async function ({ page, x, y, clip }) {
await page.touchscreen.tap(
clip ? clip.x + x : x,
clip ? clip.y + y : y
);
};
```
- Use `page` or `mobilePage` for web, or `appWindow` for Electron, as the `surface`.
- Treat `clip` as CSS pixels from `getBoundingClientRect()` in the renderer.
- Prefer JPEG at `quality: 85` unless lossless fidelity is specifically required.
- For full-image captures, use returned `{ x, y }` directly.
- For clipped captures, add the clip origin back when clicking.
### Web CSS normalization
Preferred web path for explicit-viewport contexts, and often for web in general:
```javascript
await emitWebJpeg(page);
```
Mobile web uses the same path; substitute `mobilePage` for `page`:
```javascript
await emitWebJpeg(mobilePage);
```
If the model returns `{ x, y }`, click it directly:
```javascript
await clickCssPoint({ surface: page, x, y });
```
Mobile web click path:
```javascript
await tapCssPoint({ page: mobilePage, x, y });
```
For web `clip` screenshots or element screenshots in this normal path, `scale: "css"` usually works directly. Add the region origin back when clicking.
- `await emitWebJpeg(page, { clip })`
- `await emitWebJpeg(mobilePage, { clip })`
- `await clickCssPoint({ surface: page, clip, x, y })`
- `await tapCssPoint({ page: mobilePage, clip, x, y })`
- `await clickCssPoint({ surface: page, clip: box, x, y })` after `const box = await locator.boundingBox()`
Web native-window fallback when `scale: "css"` still comes back at device-pixel size:
```javascript
var emitWebScreenshotCssScaled = async function ({ page, clip, quality = 0.85 } = {}) {
var NodeBuffer = (await import("node:buffer")).Buffer;
const target = clip
? { width: clip.width, height: clip.height }
: await page.evaluate(() => ({
width: window.innerWidth,
height: window.innerHeight,
}));
const screenshotBuffer = await page.screenshot({
type: "png",
...(clip ? { clip } : {}),
});
const bytes = await page.evaluate(
async ({ imageBase64, targetWidth, targetHeight, quality }) => {
const image = new Image();
image.src = `data:image/png;base64,${imageBase64}`;
await image.decode();
const canvas = document.createElement("canvas");
canvas.width = targetWidth;
canvas.height = targetHeight;
const ctx = canvas.getContext("2d");
ctx.imageSmoothingEnabled = true;
ctx.drawImage(image, 0, 0, targetWidth, targetHeight);
const blob = await new Promise((resolve) =>
canvas.toBlob(resolve, "image/jpeg", quality)
);
return new Uint8Array(await blob.arrayBuffer());
},
{
imageBase64: NodeBuffer.from(screenshotBuffer).toString("base64"),
targetWidth: target.width,
targetHeight: target.height,
quality,
}
);
await emitJpeg(bytes);
};
```
For a full viewport fallback capture, treat returned `{ x, y }` as direct CSS coordinates:
```javascript
await emitWebScreenshotCssScaled({ page });
await clickCssPoint({ surface: page, x, y });
```
For a clipped fallback capture, add the clip origin back:
```javascript
await emitWebScreenshotCssScaled({ page, clip });
await clickCssPoint({ surface: page, clip, x, y });
```
### Electron CSS normalization
For Electron, normalize in the main process instead of opening a scratch Playwright page. The helper below returns CSS-scaled bytes for the full content area or for a clipped CSS-pixel region. Treat `clip` as content-area CSS pixels, for example values taken from `getBoundingClientRect()` in the renderer.
```javascript
var emitElectronScreenshotCssScaled = async function ({ electronApp, clip, quality = 85 } = {}) {
const bytes = await electronApp.evaluate(async ({ BrowserWindow }, { clip, quality }) => {
const win = BrowserWindow.getAllWindows()[0];
const image = clip ? await win.capturePage(clip) : await win.capturePage();
const target = clip
? { width: clip.width, height: clip.height }
: (() => {
const [width, height] = win.getContentSize();
return { width, height };
})();
const resized = image.resize({
width: target.width,
height: target.height,
quality: "best",
});
return resized.toJPEG(quality);
}, { clip, quality });
await emitJpeg(bytes);
};
```
Full Electron window:
```javascript
await emitElectronScreenshotCssScaled({ electronApp });
await clickCssPoint({ surface: appWindow, x, y });
```
Clipped Electron region using CSS pixels from the renderer:
```javascript
var clip = await appWindow.evaluate(() => {
const rect = document.getElementById("board").getBoundingClientRect();
return {
x: Math.round(rect.x),
y: Math.round(rect.y),
width: Math.round(rect.width),
height: Math.round(rect.height),
};
});
await emitElectronScreenshotCssScaled({ electronApp, clip });
await clickCssPoint({ surface: appWindow, clip, x, y });
```
### Raw Screenshot Exception Examples
Use these only when raw pixels matter more than CSS-coordinate alignment, such as Retina or DPI artifact debugging, pixel-accurate rendering inspection, or other fidelity-sensitive review.
Web desktop raw emit:
```javascript
await codex.emitImage({
bytes: await page.screenshot({ type: "jpeg", quality: 85 }),
mimeType: "image/jpeg",
});
```
Electron raw emit:
```javascript
await codex.emitImage({
bytes: await appWindow.screenshot({ type: "jpeg", quality: 85 }),
mimeType: "image/jpeg",
});
```
Mobile raw emit after the mobile web context is already running:
```javascript
await codex.emitImage({
bytes: await mobilePage.screenshot({ type: "jpeg", quality: 85 }),
mimeType: "image/jpeg",
});
```
## Viewport Fit Checks (Required)
Do not assume a screenshot is acceptable just because the main widget is visible. Before signoff, explicitly verify that the intended initial view matches the product requirement, using both screenshot review and numeric checks.
- Define the intended initial view before signoff. For scrollable pages, this is the above-the-fold experience. For app-like shells, games, editors, dashboards, or tools, this is the full interactive surface plus the controls and status needed to use it.
- Use screenshots as the primary evidence for fit. Numeric checks support the screenshots; they do not overrule visible clipping.
- Signoff fails if any required visible region is clipped, cut off, obscured, or pushed outside the viewport in the intended initial view, even if page-level scroll metrics appear acceptable.
- Scrolling is acceptable when the product is designed to scroll and the initial view still communicates the core experience and exposes the primary call to action or required starting context.
- For fixed-shell interfaces, scrolling is not an acceptable workaround if it is needed to reach part of the primary interactive surface or essential controls.
- Do not rely on document scroll metrics alone. Fixed-height shells, internal panes, and hidden-overflow containers can clip required UI while page-level scroll checks still look clean.
- Check region bounds, not just document bounds. Verify that each required visible region fits within the viewport in the startup state.
- For Electron or desktop apps, verify both the launched window size and placement and the renderer's initial visible layout before any manual resize or repositioning.
- Passing viewport-fit checks only proves that the intended initial view is visible without unintended clipping or scrolling. It does not prove that the UI is visually correct or aesthetically successful.
Web or renderer check:
```javascript
console.log(await page.evaluate(() => ({
innerWidth: window.innerWidth,
innerHeight: window.innerHeight,
clientWidth: document.documentElement.clientWidth,
clientHeight: document.documentElement.clientHeight,
scrollWidth: document.documentElement.scrollWidth,
scrollHeight: document.documentElement.scrollHeight,
canScrollX: document.documentElement.scrollWidth > document.documentElement.clientWidth,
canScrollY: document.documentElement.scrollHeight > document.documentElement.clientHeight,
})));
```
Electron check:
```javascript
console.log(await appWindow.evaluate(() => ({
innerWidth: window.innerWidth,
innerHeight: window.innerHeight,
clientWidth: document.documentElement.clientWidth,
clientHeight: document.documentElement.clientHeight,
scrollWidth: document.documentElement.scrollWidth,
scrollHeight: document.documentElement.scrollHeight,
canScrollX: document.documentElement.scrollWidth > document.documentElement.clientWidth,
canScrollY: document.documentElement.scrollHeight > document.documentElement.clientHeight,
})));
```
Augment the numeric check with `getBoundingClientRect()` checks for the required visible regions in your specific UI when clipping is a realistic failure mode; document-level metrics alone are not sufficient for fixed shells.
## Dev Server
For local web debugging, keep the app running in a persistent TTY session. Do not rely on one-shot background commands from a short-lived shell.
Use the project's normal start command, for example:
```bash
npm start
```
Before `page.goto(...)`, verify the chosen port is listening and the app responds.
For Electron debugging, launch the app from `js_repl` through `_electron.launch(...)` so the same session owns the process. If the Electron renderer depends on a separate dev server (for example Vite or Next), keep that server running in a persistent TTY session and then relaunch or reload the Electron app from `js_repl`.
## Cleanup
Only run cleanup when the task is actually finished:
- This cleanup is manual. Exiting Codex, closing the terminal, or losing the `js_repl` session does not implicitly run `electronApp.close()`, `context.close()`, or `browser.close()`.
- For Electron specifically, assume the app may keep running if you leave the session without executing the cleanup cell first.
```javascript
if (electronApp) {
await electronApp.close().catch(() => {});
}
if (mobileContext) {
await mobileContext.close().catch(() => {});
}
if (context) {
await context.close().catch(() => {});
}
if (browser) {
await browser.close().catch(() => {});
}
browser = undefined;
context = undefined;
page = undefined;
mobileContext = undefined;
mobilePage = undefined;
electronApp = undefined;
appWindow = undefined;
console.log("Playwright session closed");
```
If you plan to exit Codex immediately after debugging, run the cleanup cell first and wait for the `"Playwright session closed"` log before quitting.
## Common Failure Modes
- `Cannot find module 'playwright'`: run the one-time setup in the current workspace and verify the import before using `js_repl`.
- Playwright package is installed but the browser executable is missing: run `npx playwright install chromium`.
- `page.goto: net::ERR_CONNECTION_REFUSED`: make sure the dev server is still running in a persistent TTY session, recheck the port, and prefer `http://127.0.0.1:<port>`.
- `electron.launch` hangs, times out, or exits immediately: verify the local `electron` dependency, confirm the `args` target, and make sure any renderer dev server is already running before launch.
- `Identifier has already been declared`: reuse the existing top-level bindings, choose a new name, or wrap the code in `{ ... }`. Use `js_repl_reset` only when the kernel is genuinely stuck.
- `browserContext.newPage: Protocol error (Target.createTarget): Not supported` while working with Electron: do not use `appWindow.context().newPage()` or `electronApp.context().newPage()` as a scratch page; use the Electron-specific screenshot normalization flow in the model-bound screenshots section.
- `js_repl` timed out or reset: rerun the bootstrap cell and recreate the session with shorter, more focused cells.
- Browser launch or network operations fail immediately: confirm the session was started with `--sandbox danger-full-access` and restart that way if needed.
.blackbox/skills/playwright-interactive/agents/openai.yaml
+6
View File
@@ -0,0 +1,6 @@
interface:
display_name: "Playwright Interactive"
short_description: "Persistent browser and Electron QA"
icon_small: "./assets/playwright-small.svg"
icon_large: "./assets/playwright.png"
default_prompt: "Use $playwright-interactive to debug a local web or Electron app in a persistent Playwright session and capture the QA evidence."
.blackbox/skills/playwright-interactive/assets/playwright-small.svg
+3
View File
@@ -0,0 +1,3 @@
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
<path fill="#0D0D0D" d="m8.55 7.568.124.028 5.16 1.548.137.054c.606.294.645 1.165.068 1.512l-.133.066-2.236.894-.894 2.236c-.285.713-1.263.714-1.578.065l-.054-.138-1.548-5.16a.866.866 0 0 1 .954-1.105ZM10 12.983l.715-1.787.037-.08a.865.865 0 0 1 .445-.402L12.983 10 8.721 8.72l1.278 4.262ZM4.723 10.38a.532.532 0 0 1 .752.752l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414ZM2.27 5.86l1.932.517.1.039a.533.533 0 0 1-.269 1.007l-.106-.018-1.932-.517-.101-.039a.532.532 0 0 1 .27-1.006l.106.017Zm9.608-2.62a.532.532 0 0 1 .668.82l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414.084-.068ZM6.237 1.618a.532.532 0 0 1 .652.377l.518 1.932.017.106a.533.533 0 0 1-1.007.27l-.039-.101-.517-1.932-.017-.106a.532.532 0 0 1 .393-.546Z"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 843 B

.blackbox/skills/playwright-interactive/assets/playwright.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

.blackbox/skills/playwright/LICENSE.txt
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright (c) Microsoft Corporation.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.blackbox/skills/playwright/NOTICE.txt
+14
View File
@@ -0,0 +1,14 @@
This skill includes material derived from the Microsoft playwright-cli repository.
Source:
- Repository: microsoft/playwright-cli
- Path: skills/playwright-cli/SKILL.md
Copyright (c) Microsoft Corporation.
Licensed under the Apache License, Version 2.0.
See LICENSE.txt in this directory.
Modifications:
- Adapted for the Codex skill collection.
- Added a wrapper script and local reference guides.
.blackbox/skills/playwright/SKILL.md
+147
View File
@@ -0,0 +1,147 @@
---
name: "playwright"
description: "Use when the task requires automating a real browser from the terminal (navigation, form filling, snapshots, screenshots, data extraction, UI-flow debugging) via `playwright-cli` or the bundled wrapper script."
---
# Playwright CLI Skill
Drive a real browser from the terminal using `playwright-cli`. Prefer the bundled wrapper script so the CLI works even when it is not globally installed.
Treat this skill as CLI-first automation. Do not pivot to `@playwright/test` unless the user explicitly asks for test files.
## Prerequisite check (required)
Before proposing commands, check whether `npx` is available (the wrapper depends on it):
```bash
command -v npx >/dev/null 2>&1
```
If it is not available, pause and ask the user to install Node.js/npm (which provides `npx`). Provide these steps verbatim:
```bash
# Verify Node/npm are installed
node --version
npm --version
# If missing, install Node.js/npm, then:
npm install -g @playwright/cli@latest
playwright-cli --help
```
Once `npx` is present, proceed with the wrapper script. A global install of `playwright-cli` is optional.
## Skill path (set once)
```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
```
User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
## Quick start
Use the wrapper script:
```bash
"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot
```
If the user prefers a global install, this is also valid:
```bash
npm install -g @playwright/cli@latest
playwright-cli --help
```
## Core workflow
1. Open the page.
2. Snapshot to get stable element refs.
3. Interact using refs from the latest snapshot.
4. Re-snapshot after navigation or significant DOM changes.
5. Capture artifacts (screenshot, pdf, traces) when useful.
Minimal loop:
```bash
"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot
```
## When to snapshot again
Snapshot again after:
- navigation
- clicking elements that change the UI substantially
- opening/closing modals or menus
- tab switches
Refs can go stale. When a command fails due to a missing ref, snapshot again.
## Recommended patterns
### Form fill and submit
```bash
"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot
```
### Debug a UI flow with traces
```bash
"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
# ...interactions...
"$PWCLI" tracing-stop
```
### Multi-tab work
```bash
"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot
```
## Wrapper script
The wrapper script uses `npx --package @playwright/cli playwright-cli` so the CLI can run without a global install:
```bash
"$PWCLI" --help
```
Prefer the wrapper unless the repository already standardizes on a global install.
## References
Open only what you need:
- CLI command reference: `references/cli.md`
- Practical workflows and troubleshooting: `references/workflows.md`
## Guardrails
- Always snapshot before referencing element ids like `e12`.
- Re-snapshot when refs seem stale.
- Prefer explicit commands over `eval` and `run-code` unless needed.
- When you do not have a fresh snapshot, use placeholder refs like `eX` and say why; do not bypass refs with `run-code`.
- Use `--headed` when a visual check will help.
- When capturing artifacts in this repo, use `output/playwright/` and avoid introducing new top-level artifact folders.
- Default to CLI commands and workflows, not Playwright test specs.
.blackbox/skills/playwright/agents/openai.yaml
+6
View File
@@ -0,0 +1,6 @@
interface:
display_name: "Playwright CLI Skill"
short_description: "Automate real browsers from the terminal"
icon_small: "./assets/playwright-small.svg"
icon_large: "./assets/playwright.png"
default_prompt: "Automate this browser workflow with Playwright and produce a reliable script with run steps."
.blackbox/skills/playwright/assets/playwright-small.svg
+3
View File
@@ -0,0 +1,3 @@
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
<path d="m8.55 7.568.124.028 5.16 1.548.137.054c.606.294.645 1.165.068 1.512l-.133.066-2.236.894-.894 2.236c-.285.713-1.263.714-1.578.065l-.054-.138-1.548-5.16a.866.866 0 0 1 .954-1.105ZM10 12.983l.715-1.787.037-.08a.865.865 0 0 1 .445-.402L12.983 10 8.721 8.72l1.278 4.262ZM4.723 10.38a.532.532 0 0 1 .752.752l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414ZM2.27 5.86l1.932.517.1.039a.533.533 0 0 1-.269 1.007l-.106-.018-1.932-.517-.101-.039a.532.532 0 0 1 .27-1.006l.106.017Zm9.608-2.62a.532.532 0 0 1 .668.82l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414.084-.068ZM6.237 1.618a.532.532 0 0 1 .652.377l.518 1.932.017.106a.533.533 0 0 1-1.007.27l-.039-.101-.517-1.932-.017-.106a.532.532 0 0 1 .393-.546Z"/>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 828 B

.blackbox/skills/playwright/assets/playwright.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

.blackbox/skills/playwright/references/cli.md
+116
View File
@@ -0,0 +1,116 @@
# Playwright CLI Reference
Use the wrapper script unless the CLI is already installed globally:
```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
"$PWCLI" --help
```
User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
Optional convenience alias:
```bash
alias pwcli="$PWCLI"
```
## Core
```bash
pwcli open https://example.com
pwcli close
pwcli snapshot
pwcli click e3
pwcli dblclick e7
pwcli type "search terms"
pwcli press Enter
pwcli fill e5 "user@example.com"
pwcli drag e2 e8
pwcli hover e4
pwcli select e9 "option-value"
pwcli upload ./document.pdf
pwcli check e12
pwcli uncheck e12
pwcli eval "document.title"
pwcli eval "el => el.textContent" e5
pwcli dialog-accept
pwcli dialog-accept "confirmation text"
pwcli dialog-dismiss
pwcli resize 1920 1080
```
## Navigation
```bash
pwcli go-back
pwcli go-forward
pwcli reload
```
## Keyboard
```bash
pwcli press Enter
pwcli press ArrowDown
pwcli keydown Shift
pwcli keyup Shift
```
## Mouse
```bash
pwcli mousemove 150 300
pwcli mousedown
pwcli mousedown right
pwcli mouseup
pwcli mouseup right
pwcli mousewheel 0 100
```
## Save as
```bash
pwcli screenshot
pwcli screenshot e5
pwcli pdf
```
## Tabs
```bash
pwcli tab-list
pwcli tab-new
pwcli tab-new https://example.com/page
pwcli tab-close
pwcli tab-close 2
pwcli tab-select 0
```
## DevTools
```bash
pwcli console
pwcli console warning
pwcli network
pwcli run-code "await page.waitForTimeout(1000)"
pwcli tracing-start
pwcli tracing-stop
```
## Sessions
Use a named session to isolate work:
```bash
pwcli --session todo open https://demo.playwright.dev/todomvc
pwcli --session todo snapshot
```
Or set an environment variable once:
```bash
export PLAYWRIGHT_CLI_SESSION=todo
pwcli open https://demo.playwright.dev/todomvc
```
.blackbox/skills/playwright/references/workflows.md
+95
View File
@@ -0,0 +1,95 @@
# Playwright CLI Workflows
Use the wrapper script and snapshot often.
Assume `PWCLI` is set and `pwcli` is an alias for `"$PWCLI"`.
In this repo, run commands from `output/playwright/<label>/` to keep artifacts contained.
## Standard interaction loop
```bash
pwcli open https://example.com
pwcli snapshot
pwcli click e3
pwcli snapshot
```
## Form submission
```bash
pwcli open https://example.com/form --headed
pwcli snapshot
pwcli fill e1 "user@example.com"
pwcli fill e2 "password123"
pwcli click e3
pwcli snapshot
pwcli screenshot
```
## Data extraction
```bash
pwcli open https://example.com
pwcli snapshot
pwcli eval "document.title"
pwcli eval "el => el.textContent" e12
```
## Debugging and inspection
Capture console messages and network activity after reproducing an issue:
```bash
pwcli console warning
pwcli network
```
Record a trace around a suspicious flow:
```bash
pwcli tracing-start
# reproduce the issue
pwcli tracing-stop
pwcli screenshot
```
## Sessions
Use sessions to isolate work across projects:
```bash
pwcli --session marketing open https://example.com
pwcli --session marketing snapshot
pwcli --session checkout open https://example.com/checkout
```
Or set the session once:
```bash
export PLAYWRIGHT_CLI_SESSION=checkout
pwcli open https://example.com/checkout
```
## Configuration file
By default, the CLI reads `playwright-cli.json` from the current directory. Use `--config` to point at a specific file.
Minimal example:
```json
{
"browser": {
"launchOptions": {
"headless": false
},
"contextOptions": {
"viewport": { "width": 1280, "height": 720 }
}
}
}
```
## Troubleshooting
- If an element ref fails, run `pwcli snapshot` again and retry.
- If the page looks wrong, re-open with `--headed` and resize the window.
- If a flow depends on prior state, use a named `--session`.
.blackbox/skills/playwright/scripts/playwright_cli.sh
Executable
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env bash
set -euo pipefail
if ! command -v npx >/dev/null 2>&1; then
echo "Error: npx is required but not found on PATH." >&2
exit 1
fi
has_session_flag="false"
for arg in "$@"; do
case "$arg" in
--session|--session=*)
has_session_flag="true"
break
;;
esac
done
cmd=(npx --yes --package @playwright/cli playwright-cli)
if [[ "${has_session_flag}" != "true" && -n "${PLAYWRIGHT_CLI_SESSION:-}" ]]; then
cmd+=(--session "${PLAYWRIGHT_CLI_SESSION}")
fi
cmd+=("$@")
exec "${cmd[@]}"
.blackbox/skills/security-best-practices/LICENSE.txt
+201
View File
@@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf of
any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don\'t include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.blackbox/skills/security-best-practices/SKILL.md
+86
View File
@@ -0,0 +1,86 @@
---
name: "security-best-practices"
description: "Perform language and framework specific security best-practice reviews and suggest improvements. Trigger only when the user explicitly requests security best practices guidance, a security review/report, or secure-by-default coding help. Trigger only for supported languages (python, javascript/typescript, go). Do not trigger for general code review, debugging, or non-security tasks."
---
# Security Best Practices
## Overview
This skill provides a description of how to identify the language and frameworks used by the current context, and then to load information from this skill's references directory about the security best practices for this language and or frameworks.
This information, if present, can be used to write new secure by default code, or to passively detect major issues within existing code, or (if requested by the user) provide a vulnerability report and suggest fixes.
## Workflow
The initial step for this skill is to identify ALL languages and ALL frameworks which you are being asked to use or already exist in the scope of the project you are working in. Focus on the primary core frameworks. Often you will want to identify both frontend and backend languages and frameworks.
Then check this skill's references directory to see if there are any relevant documentation for the language and or frameworks. Make sure you read ALL reference files which relate to the specific framework or language. The format of the filenames is `<language>-<framework>-<stack>-security.md`. You should also check if there is a `<language>-general-<stack>-security.md` which is agnostic to the framework you may be using.
If working on a web application which includes a frontend and a backend, make sure you have checked for reference documents for BOTH the frontend and backend!
If you are asked to make a web app which will include both a frontend and backend, but the frontend framework is not specified, also check out `javascript-general-web-frontend-security.md`. It is important that you understand how to secure both the frontend and backend.
If no relevant information is available in the skill's references directory, think a little bit about what you know about the language, the framework, and all well known security best practices for it. If you are unsure you can try to search online for documentation on security best practices.
From there it can operate in a few ways.
1. The primary mode is to just use the information to write secure by default code from this point forward. This is useful for starting a new project or when writing new code.
2. The secondary mode is to passively detect vulnerabilities while working in the project and writing code for the user. Critical or very important vulnerabilities or major issues going against security guidance can be flagged and the user can be told about them. This passive mode should focus on the largest impact vulnerabilities and secure defaults.
3. The user can ask for a security report or to improve the security of the codebase. In this case a full report should be produced describe anyways the project fails to follow security best practices guidance. The report should be prioritized and have clear sections of severity and urgency. Then offer to start working on fixes for these issues. See #fixes below.
## Workflow Decision Tree
- If the language/framework is unclear, inspect the repo to determine it and list your evidence.
- If matching guidance exists in `references/`, load only the relevant files and follow their instructions.
- If no matching guidance exists, consider if you know any well known security best practices for the chosen language and or frameworks, but if asked to generate a report, let the user know that concrete guidance is not available (you can still generate the report or detect for sure critical vulnerabilities)
# Overrides
While these references contain the security best practices for languages and frameworks, customers may have cases where they need to bypass or override these practices. Pay attention to specific rules and instructions in the project's documentation and prompt files which may require you to override certain best practices. When overriding a best practice, you MAY report it to the user, but do not fight with them. If a security best practice needs to be bypassed / ignored for some project specific reason, you can also suggest to add documentation about this to the project so it is clear why the best practice is not being followed and to follow that bypass in the future.
# Report Format
When producing a report, you should write the report as a markdown file in `security_best_practices_report.md` or some other location if provided by the user. You can ask the user where they would like the report to be written to.
The report should have a short executive summary at the top.
The report should be clearly delineated into multiple sections based on severity of the vulnerability. The report should focus on the most critical findings as these have the highest impact for the user. All findings should be noted with an numeric ID to make them easier to reference.
For critical findings include a one sentence impact statement.
Once the report is written, also report it to the user directly, although you may be less verbose. You can offer to explain any of the findings or the reasons behind the security best practices guidance if the user wants more info on any findings.
Important: When referencing code in the report, make sure to find and include line numbers for the code you are referencing.
After you write the report file, summarize the findings to the user.
Also tell the user where the final report was written to
# Fixes
If you produced a report, let the user read the report and ask to begin performing fixes.
If you passively found a critical finding, notify the user and ask if they would like you to fix this finding.
When producing fixes, focus on fixing a single finding at a time. The fixes should have concise clear comments explaining that the new code is based on the specific security best practice, and perhaps a very short reason why it would be dangerous to not do it in this way.
Always consider if the changes you want to make will impact the functionality of the user's code. Consider if the changes may cause regressions with how the project works currently. It is often the case that insecure code is relied on for other reasons (and this is why insecure code lives on for so long). Avoid breaking the user's project as this may make them not want to apply security fixes in the future. It is better to write a well thought out, well informed by the rest of the project, fix, then a quick slapdash change.
Always follow any normal change or commit flow the user has configured. If making git commits, provide clear commit messages explaining this is to align with security best practices. Try to avoid bunching a number of unrelated findings into a single commit.
Always follow any normal testing flows the user has configured (if any) to confirm that your changes are not introducing regressions. Consider the second order impacts the changes may have and inform the user before making them if there are any.
# General Security Advice
Below is a few bits of secure coding advice that applies to almost any language or framework.
### Avoid Using Incrementing IDs for Public IDs of Resources
When assigning an ID for some resource, which will then be used by exposed to the internet, avoid using small auto-incrementing IDs. Use longer, random UUID4 or random hex string instead. This will prevent users from learning the quantity of a resource and being able to guess resource IDs.
### A note on TLS
While TLS is important for production deployments, most development work will be with TLS disabled or provided by some out-of-scope TLS proxy. Due to this, be very careful about not reporting lack of TLS as a security issue. Also be very careful around use of "secure" cookies. They should only be set if the application will actually be over TLS. If they are set on non-TLS applications (such as when deployed for local dev or testing), it will break the application. You can provide a env or other flag to override setting secure as a way to keep it off until on a TLS production deployment. Additionally avoid recommending HSTS. It is dangerous to use without full understanding of the lasting impacts (can cause major outages and user lockout) and it is not generally recommended for the scope of projects being reviewed by codex.
.blackbox/skills/security-best-practices/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "Security Best Practices"
short_description: "Security reviews and secure-by-default guidance"
default_prompt: "Review this codebase for security best practices and suggest secure-by-default improvements."
.blackbox/skills/security-best-practices/references/golang-general-backend-security.md
+826
View File
@@ -0,0 +1,826 @@
# Go (Golang) Security Spec (Go 1.25.x, Standard Library, net/http)
This document is designed as a **security spec** that supports:
1) **Secure-by-default code generation** for new Go code.
2) **Security review / vulnerability hunting** in existing Go code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
--------------------------------------------------------------------
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
- MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session cookies, JWTs, database URLs with credentials, signing keys, client secrets).
- MUST NOT “fix” security by disabling protections (e.g., `InsecureSkipVerify`, `GOSUMDB=off` for public modules, wildcard CORS + credentials, removing auth checks, disabling CSRF defenses on cookie-auth apps).
- MUST provide **evidence-based findings** during audits: cite file paths, code snippets, build/deploy configs, and concrete values that justify the claim.
- MUST treat uncertainty honestly: if a control might exist in infrastructure (reverse proxy, WAF, service mesh, platform config), report it as “not visible in app code; verify at runtime/config.”
- MUST keep fixes minimal, correct, and production-safe; avoid introducing breaking changes without warning (especially around auth/session flows, and proxies).
--------------------------------------------------------------------
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new Go code or modify existing code:
- MUST follow every **MUST** requirement in this spec.
- SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
- MUST prefer safe-by-default APIs and proven libraries over custom security code.
- MUST avoid introducing new risky sinks (shell execution, dynamic template execution, serving user files as HTML, unsafe redirects, weak crypto, unbounded parsing, etc.).
### 1.2 Passive review mode (always on while editing)
While working anywhere in a Go repo (even if the user did not ask for a security scan):
- MUST “notice” violations of this spec in touched/nearby code.
- SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
- MUST systematically search the codebase for violations of this spec.
- MUST output findings in a structured format (see §2.3).
Recommended audit order:
1) Build/deploy entrypoints: `main.go`, `cmd/*`, Dockerfiles, Kubernetes manifests, systemd units, CI workflows.
2) Go toolchain & dependency policy: Go version, modules, `go.mod/go.sum`, proxy/sumdb settings, govulncheck usage.
3) Secret management and config loading (env, files, secret stores) + logging patterns.
4) HTTP server configuration (timeouts, body limits, proxy trust, security headers).
5) AuthN/AuthZ boundaries, session/cookie settings, token validation.
6) CSRF protections for cookie-authenticated state-changing endpoints.
7) Template usage and output encoding (XSS), and any “render template from string” behavior (SSTI).
8) File handling (uploads/downloads/path traversal/temp files), static file serving.
9) Injection sinks: SQL, OS command execution, SSRF/outbound fetch, open redirects.
10) Concurrency/resource exhaustion (unbounded goroutines/queues, missing timeouts/contexts).
11) Use of `unsafe` / `cgo` / `reflect` in security-sensitive paths.
12) Debug/diagnostic endpoints (pprof/expvar/metrics) exposure.
13) Cryptography usage (randomness, password hashing).
--------------------------------------------------------------------
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
- `*http.Request` fields: `r.URL.Path`, `r.URL.RawQuery`, `r.Form`, `r.PostForm`, headers, cookies, `r.Body`
- Path parameters from routers (including values extracted from URL paths)
- JSON/XML/YAML bodies, multipart form parts, uploaded files
- Any data from external systems (webhooks, third-party APIs, message queues)
- Any persisted user content (DB rows) that originated from users
- Configuration values that might be attacker-influenced in some deployments (headers set by upstream proxies, environment variables in multi-tenant systems)
### 2.2 State-changing request
A request is state-changing if it can create/update/delete data, change auth/session state, trigger side effects (purchase, email send, webhook send), or initiate privileged actions.
### 2.3 Required audit finding format
For each issue found, output:
- Rule ID:
- Severity: Critical / High / Medium / Low
- Location: file path + function/handler name + line(s)
- Evidence: the exact code/config snippet
- Impact: what could go wrong, who can exploit it
- Fix: safe change (prefer minimal diff)
- Mitigation: defense-in-depth if immediate fix is hard
- False positive notes: what to verify if uncertain (edge configs, proxy behavior, auth assumptions)
--------------------------------------------------------------------
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common Go misconfigurations.
### 3.1 Toolchain, patching, and dependency hygiene (MUST)
- MUST run a supported Go major version and keep to the latest patch releases.
- MUST treat Go standard library patch releases as security-relevant (many security fixes land in stdlib components like `net/http`, `crypto/*`, parsing packages).
- MUST use Go modules with committed `go.mod` and `go.sum`.
- MUST NOT disable module authenticity mechanisms for public modules (checksum DB) unless you have a controlled, documented replacement.
- MUST run `govulncheck` (source scan and/or binary scan) in CI and address findings.
### 3.2 HTTP server baseline (MUST for network-facing services)
If the program serves HTTP (directly or via a framework built on `net/http`):
- MUST configure an `http.Server` with explicit timeouts and header limits.
- MUST set request body size limits (global and per-route as needed).
- MUST avoid exposing diagnostic endpoints (pprof/expvar) publicly.
- SHOULD set a consistent set of security headers (or verify they are set at the edge).
- MUST set cookie security attributes for any cookies you issue.
- SHOULD implement rate limiting and abuse controls for auth and expensive endpoints.
Illustrative baseline skeleton (adjust to your project):
- Create a dedicated mux (avoid implicit global defaults unless intentionally managed).
- Wrap handlers with: panic-safe error handling, request ID, logging, auth, and limits.
--------------------------------------------------------------------
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### GO-DEPLOY-001: Keep the Go toolchain and standard library updated (security releases)
Severity: Medium
NOTE: Upgrading dependencies and the core Go version can break projects in unexpected ways. Focus on only security-critical dependencies and if noticed, let the user know rather than upgrading automatically.
Required:
- MUST run a supported Go major release and apply patch releases promptly.
- SHOULD treat patch releases as security-relevant, even if your application code didn’t change.
Insecure patterns:
- Production builds pinned to old Go versions without a patching process.
- Docker images like `golang:1.xx` or custom base images that are not updated regularly.
- CI pipelines that intentionally suppress Go updates.
Detection hints:
- Inspect CI (`.github/workflows`, `gitlab-ci.yml`, etc.) for `go-version:` or toolchain setup.
- Inspect Dockerfiles for `FROM golang:` tags.
- Inspect `go.mod` `go` directive and any toolchain pinning.
Fix:
- Upgrade to the latest patch of a supported Go version.
- Add an automated check (CI) that fails when Go is below an approved minimum.
Notes:
- Go publishes regular minor releases that frequently include security fixes across standard library packages.
---
### GO-SUPPLY-001: Go module authenticity MUST NOT be disabled for public dependencies
Severity: High
Required:
- MUST keep module checksum verification enabled for public modules.
- SHOULD commit `go.sum` and treat changes as security-sensitive.
- MUST NOT use insecure module fetching settings for public modules.
- MAY configure private module behavior using `GOPRIVATE`/`GONOSUMDB` for private repos, but must do so narrowly and intentionally.
Insecure patterns:
- `GOSUMDB=off` in CI or production build environments for public modules.
- `GONOSUMDB=*` or overly broad patterns that effectively disable verification.
- `GOINSECURE=*` or broad `GOINSECURE` patterns for public modules.
- `GOPROXY=direct` everywhere without a clear policy.
Detection hints:
- Search build configs for `GOSUMDB`, `GONOSUMDB`, `GOINSECURE`, `GOPROXY`, `GOPRIVATE`.
- Look for documentation/scripts that recommend disabling checksum DB “to make builds work”.
Fix:
- Restore defaults for public module verification.
- For private modules:
- Set `GOPRIVATE=your.private.domain/*`
- Configure an internal proxy or direct fetching, and restrict `GONOSUMDB` to private patterns only.
Notes:
- Disabling checksum verification removes an important integrity layer against targeted or compromised upstream delivery.
---
### GO-CONFIG-001: Secrets must be externalized and never logged or committed
Severity: High (Critical if credentials are committed)
Required:
- MUST load secrets from environment variables, secret managers, or secure config files with restricted permissions.
- MUST NOT hard-code secrets in Go source, test fixtures that may reach production, or build args.
- MUST NOT log secrets or full credential-bearing connection strings.
- SHOULD fail closed in production if required secrets are missing.
Insecure patterns:
- String constants containing tokens/keys/passwords.
- `.env` files or config files with secrets committed to repo.
- Logging `os.Environ()`, dumping full configs, or printing DSNs.
Detection hints:
- Search for suspicious literals (`API_KEY`, `SECRET`, `PASSWORD`, `Authorization:`).
- Inspect config loaders and logging statements.
- Inspect CI logs or debug print paths.
Fix:
- Move secrets to a secret store / environment variables.
- Redact sensitive fields in logs.
- Add secret scanning to CI and pre-commit.
---
### GO-HTTP-001: HTTP servers MUST set timeouts and MaxHeaderBytes
Severity: High (DoS risk)
Required:
- MUST set: `ReadHeaderTimeout`, and SHOULD set `ReadTimeout`, `WriteTimeout`, `IdleTimeout` as appropriate for the service.
- MUST set `MaxHeaderBytes` to a justified limit for your application.
- MUST NOT rely on default zero-values for timeouts in production for internet-facing servers.
Insecure patterns:
- `http.ListenAndServe(":8080", handler)` with a default `http.Server` (no explicit timeouts).
- `&http.Server{}` with timeouts left at zero.
- Missing `MaxHeaderBytes`.
Detection hints:
- Search for `http.ListenAndServe(`, `ListenAndServeTLS(`, `Server{` and inspect configured fields.
- Check for reverse proxies; even with a proxy, app-level timeouts still matter.
Fix:
- Use `http.Server{ReadHeaderTimeout: ..., ReadTimeout: ..., WriteTimeout: ..., IdleTimeout: ..., MaxHeaderBytes: ...}`.
- Calibrate timeouts per endpoint type (streaming vs JSON APIs).
Notes:
- Net/http documents that these timeouts exist and that zero/negative values mean “no timeout”; production services should choose explicit values.
---
### GO-HTTP-002: Request body and multipart parsing MUST be size-bounded
Severity: Medium (DoS risk; can be High for upload-heavy apps)
Required:
- MUST enforce a global maximum request body size for endpoints that accept bodies.
- MUST enforce strict multipart upload limits and avoid unbounded form parsing.
- SHOULD enforce per-route limits when some endpoints legitimately need larger bodies.
- SHOULD set upstream (proxy) limits as defense-in-depth.
Insecure patterns:
- Reading `r.Body` with `io.ReadAll(r.Body)` without a size cap.
- Calling `r.ParseMultipartForm(...)` with overly large limits (or forgetting size controls).
- Accepting file uploads with no limits on file size, number of parts, or total body size.
Detection hints:
- Search for `io.ReadAll(r.Body)`, `json.NewDecoder(r.Body)`, `ParseMultipartForm`, `FormFile`, `multipart`.
- Look for missing `http.MaxBytesReader` or equivalent per-handler limiting.
- Look for “upload” endpoints and check limits.
Fix:
- Wrap request bodies with `http.MaxBytesReader(w, r.Body, maxBytes)` before parsing.
- For multipart, set conservative limits and validate file sizes/part counts explicitly.
- Set proxy limits (e.g., at ingress) in addition to app limits.
Notes:
- There are known vulnerability classes and advisories related to excessive resource consumption in multipart/form parsing; treat unbounded parsing as a security issue.
---
### GO-DEPLOY-002: Diagnostic endpoints (pprof/expvar/metrics) MUST NOT be publicly exposed
Severity: High
NOTE: This only applies to production configurations. These endpoints are often used for debug or dev endpoints. If found, confirm that it would be reachable from the actual production deployment.
Required:
- MUST NOT expose `net/http/pprof` handlers on a public internet-facing listener without strong access controls.
- SHOULD run diagnostics on a separate, internal-only listener (loopback/VPC-only) and require auth.
- MUST review what diagnostic endpoints reveal (stack traces, memory, command lines, environment, internal URLs).
Insecure patterns:
- Side-effect import `import _ "net/http/pprof"` in a server binary with a public mux.
- `/debug/pprof/*` reachable without auth.
- `/debug/vars` (expvar) reachable without auth.
Detection hints:
- Search for `net/http/pprof` imports (including blank imports).
- Search for route prefixes `/debug/pprof`, `/debug/vars`.
- Check whether `http.DefaultServeMux` is used and whether any debug handlers register globally.
Fix:
- Remove diagnostics from production builds, or bind them to an internal-only listener.
- Add strong authentication/authorization (and ideally network-level restrictions).
Notes:
- pprof is typically imported for its side effect of registering HTTP handlers under `/debug/pprof/`.
---
### GO-HTTP-003: Reverse proxy and forwarded header trust MUST be explicit
Severity: High (auth, URL generation, logging/auditing correctness)
Required:
- If behind a reverse proxy, MUST define which proxy is trusted and how client IP/scheme/host are derived.
- MUST NOT trust `X-Forwarded-For`, `X-Forwarded-Proto`, `Forwarded`, or similar headers from the open internet.
- MUST ensure “secure cookie” logic, redirects, and absolute URL generation do not rely on spoofable headers.
Insecure patterns:
- Using `r.Header.Get("X-Forwarded-For")` as the client IP without validating the proxy boundary.
- Deriving “is HTTPS” from `X-Forwarded-Proto` without confirming it came from a trusted proxy.
- Using forwarded `Host` values for password reset links without allowlisting.
Detection hints:
- Search for `X-Forwarded-For`, `X-Forwarded-Proto`, `Forwarded`, `Real-IP`, and any custom “client IP” helpers.
- Inspect ingress/proxy configs; if not visible, mark as “verify at edge”.
Fix:
- Enforce proxy trust at the edge and in app:
- Accept forwarded headers only from known proxy IP ranges.
- Prefer platform-provided mechanisms where available.
- If generating external links, use a configured allowlisted canonical origin (not the request’s Host header).
---
### GO-HTTP-004: Security headers SHOULD be set (in app or at the edge)
Severity: Medium
Required (typical web app serving browsers):
- SHOULD set:
- `Content-Security-Policy` (CSP) appropriate to the app. NOTE: It is most important to set the CSP's script-src. All other directives are not as important and can generally be excluded for the ease of development.
- `X-Content-Type-Options: nosniff`
- Clickjacking protection (`X-Frame-Options` and/or CSP `frame-ancestors`)
- `Referrer-Policy` and `Permissions-Policy` where appropriate
- MUST ensure cookies have secure attributes (see GO-HTTP-005).
NOTE:
- These headers may be set via reverse proxy/CDN; if not visible in app code, report as “verify at edge”.
Insecure patterns:
- No security headers anywhere (app or edge) for a browser-facing app.
- CSP missing for apps rendering untrusted content.
Detection hints:
- Search for middleware setting headers: `w.Header().Set("Content-Security-Policy", ...)`, etc.
- Search for reverse proxy config that sets headers.
Fix:
- Add centralized header middleware in Go, or configure at the edge.
- Keep CSP realistic; avoid `unsafe-inline` where possible.
---
### GO-HTTP-005: Cookies MUST use secure attributes in production
Severity: Medium
Required (production, HTTPS):
- MUST set `Secure` on cookies that carry auth/session state. IMPORTANT NOTE: Only set `Secure` in production environment when TLS is configured. When running in a local dev environment over HTTP, do not set `Secure` property on cookies. You should do this conditionally based on if the app is running in production mode. You should also include a property like `SESSION_COOKIE_SECURE` which can be used to disable `Secure` cookies when testing over HTTP.
- MUST set `HttpOnly` on auth/session cookies.
- SHOULD set `SameSite=Lax` by default (or `Strict` if compatible), and only use `None` when necessary (and only with `Secure`).
- SHOULD set bounded lifetimes (`Max-Age`/`Expires`) appropriate to the app.
Insecure patterns:
- Setting auth/session cookies without `Secure` in HTTPS deployments.
- Cookies without `HttpOnly` for session identifiers.
- `SameSite=None` for cookie-authenticated apps without a strong CSRF strategy.
Detection hints:
- Search for `http.SetCookie`, `&http.Cookie{`, `Set-Cookie`.
- Inspect cookie flags in auth/session code.
Fix:
- Set the correct fields on `http.Cookie` and centralize cookie creation.
Notes:
- SameSite is defense-in-depth and does not replace CSRF protections for cookie-auth apps.
---
### GO-HTTP-006: Cookie-authenticated state-changing endpoints MUST be CSRF-protected
Severity: High
- IMPORTANT NOTE: If cookies are not used for auth (e.g., pure bearer token in Authorization header with no ambient cookies), CSRF is not a risk for those endpoints.
Required:
- MUST protect all state-changing endpoints (POST/PUT/PATCH/DELETE) that rely on cookies for authentication.
- SHOULD use a well-tested CSRF library/middleware rather than rolling your own.
- MAY use additional defenses (Origin/Referer checks, Fetch Metadata, SameSite cookies), but tokens remain the primary defense for cookie-authenticated apps.
If tokens are impractical, or for small applications:
* MUST at a minimum require a custom header to be set and set the session cookie SESSION_COOKIE_SAMESITE=lax, as this is the strongest method besides requiring a form token, and may be much easier to implement.
Insecure patterns:
- Cookie-authenticated JSON endpoints that mutate state with no CSRF checks.
- Using GET for state-changing actions.
Detection hints:
- Enumerate all non-GET routes and identify auth mechanism.
- Look for CSRF middleware usage; if absent, treat as suspicious in browser-facing apps.
Fix:
- Add CSRF middleware and ensure it covers all state-changing routes.
- If the service is an API intended for non-browser clients, avoid cookie auth; use Authorization headers.
---
### GO-HTTP-007: CORS must be explicit and least-privilege
Severity: Medium (High if misconfigured with credentials)
Required:
- If CORS is not needed, MUST keep it disabled.
- If CORS is needed:
- MUST allowlist trusted origins (do not reflect arbitrary origins)
- MUST be careful with credentialed requests; do not combine broad origins with cookies
- SHOULD restrict allowed methods/headers
Insecure patterns:
- `Access-Control-Allow-Origin: *` paired with cookies (`Access-Control-Allow-Credentials: true`).
- Reflecting `Origin` without validation.
Detection hints:
- Search for `Access-Control-Allow-` header setting.
- Search for CORS middleware configuration.
Fix:
- Implement strict origin allowlists and minimal methods/headers.
- Ensure cookie-auth endpoints are not exposed cross-origin unless required.
---
### GO-XSS-001: Use html/template and avoid bypassing auto-escaping with untrusted data
Severity: High
Required:
- MUST use `html/template` for HTML rendering (not `text/template`).
- MUST NOT convert untrusted data into “trusted” template types (`template.HTML`, `template.JS`, `template.URL`, etc.).
- SHOULD keep templates static and controlled by developers; treat dynamic templates as high risk.
- MUST NOT serve user-uploaded HTML/JS as active content unless explicitly intended and safely sandboxed.
Insecure patterns:
- `text/template` used to generate HTML.
- Using `template.HTML(userInput)` or similar typed wrappers.
- Directly writing unescaped user content into HTML responses.
Detection hints:
- Search for `text/template`, `template.New(...).Parse(...)`, and typed wrappers like `template.HTML(`.
- Inspect handlers that return HTML with string concatenation.
Fix:
- Use `html/template` and pass untrusted data as data, not markup.
- If you must allow limited HTML, use a vetted HTML sanitizer and still be careful with attributes/URLs.
---
### GO-SSTI-001: Never parse/execute templates from untrusted input (SSTI)
Severity: Critical
Required:
- MUST NOT call `template.Parse` / `template.ParseFiles` / `template.New(...).Parse(...)` on template text influenced by untrusted input.
- MUST treat “user-defined templates” as a special high-risk design:
- MUST use heavy sandboxing and strict allowlists
- MUST isolate execution (process/container boundary) if truly required
Insecure patterns:
- `tmpl := template.Must(template.New("x").Parse(r.FormValue("tmpl")))`
- Reading templates from uploads / DB entries and executing them in the same trust domain as server code.
Detection hints:
- Search for `.Parse(` and trace the origin of the template string.
- Look for “custom email templates”, “user theming templates”, etc.
Fix:
- Replace with safe substitution mechanisms (no code execution).
- If templates must be user-controlled, isolate and sandbox aggressively.
---
### GO-PATH-001: Prevent path traversal and unsafe file serving
Severity: High
Required:
- MUST NOT pass user-controlled paths to `os.Open`, `os.ReadFile`, `http.ServeFile`, or `http.FileServer` without strict validation and base-dir enforcement.
- MUST treat `..`, absolute paths, and OS-specific path tricks as hostile input.
- SHOULD store user uploads outside any static web root; serve through controlled handlers.
- MUST avoid directory listing for sensitive file trees.
Insecure patterns:
- `http.ServeFile(w, r, r.URL.Query().Get("path"))`
- `os.Open(filepath.Join(baseDir, userPath))` without checking that the result stays under `baseDir`
- `http.FileServer(http.Dir("."))` serving the project root or user-writable directories
Detection hints:
- Search for `ServeFile(`, `FileServer(`, `http.Dir(`, `os.Open(`, `ReadFile(`, `filepath.Join(`.
- Trace whether path components come from request/DB.
Fix:
- Use an allowlist of file identifiers (e.g., database IDs) mapped to server-side paths.
- Enforce base directory containment after cleaning and joining.
- Serve active formats as downloads (`Content-Disposition: attachment`) unless explicitly intended.
---
### GO-UPLOAD-001: File uploads must be validated, stored safely, and served safely
Severity: High
Required:
- MUST enforce upload size limits (app + edge).
- MUST validate file type using allowlists and content checks (not only extensions).
- MUST store uploads outside executable/static roots when possible.
- SHOULD generate server-side filenames (random IDs) and avoid trusting original names.
- MUST serve potentially active formats safely (download attachment) unless explicitly intended.
Insecure patterns:
- Accepting arbitrary file types and serving them back inline.
- Using user-supplied filename as storage path.
- Missing size/type validation.
Detection hints:
- Search for `multipart`, `FormFile`, `ParseMultipartForm`, `io.Copy` to disk.
- Check where files are stored and how they are served.
Fix:
- Implement allowlist validation + safe storage + safe serving.
- Add scanning/quarantine workflows where applicable.
---
### GO-INJECT-001: Prevent SQL injection (parameterized queries / ORM)
Severity: High
Required:
- MUST use parameterized queries or an ORM that parameterizes under the hood.
- MUST NOT build SQL by string concatenation / `fmt.Sprintf` / string interpolation with untrusted input.
Insecure patterns:
- `fmt.Sprintf("SELECT ... WHERE id=%s", r.URL.Query().Get("id"))`
- `query := "UPDATE users SET role='" + role + "' WHERE id=" + id`
Detection hints:
- Grep for `SELECT`, `INSERT`, `UPDATE`, `DELETE` and check how query strings are built.
- Trace untrusted data into `db.Query`, `db.Exec`, `QueryRow`, etc.
Fix:
- Replace with placeholders (`?`, `$1`, etc.) and pass parameters separately.
- Validate and type-check IDs before use.
---
### GO-INJECT-002: Prevent OS command injection; avoid shelling out with untrusted input
Severity: Critical to High (depends on exposure)
Required:
- MUST avoid executing external commands with attacker-controlled strings.
- If subprocess is necessary:
- MUST use `exec.CommandContext` with an argument list (not `sh -c`).
- MUST NOT pass untrusted input to a shell (`bash -c`, `sh -c`, PowerShell).
- SHOULD use strict allowlists for any variable component (subcommand, flags, filenames).
- MUST assume CLI tools may interpret attacker-controlled args as flags or special values.
Insecure patterns:
- `exec.Command("sh", "-c", userString)`
- `exec.Command("bash", "-c", fmt.Sprintf("tool %s", user))`
- Calling the shell to get glob expansion for user-supplied globs.
Detection hints:
- Search for `os/exec`, `exec.Command(`, `CommandContext(`, `"sh"`, `"bash"`, `"-c"`.
- Trace untrusted input into command name/args.
Fix:
- Use library APIs instead of subprocesses.
- Hardcode command and allowlist/validate args.
- If a shell is unavoidable, escape robustly and treat as high risk (prefer avoiding).
Notes:
- The Go `os/exec` package intentionally does invoke a shell; introducing `sh -c` reintroduces shell injection hazards.
---
### GO-SSRF-001: Prevent SSRF in outbound HTTP requests
Severity: Medium (High in cloud/LAN environments)
- Note: For small stand alone projects this is less important. It is most important when deploying into an LAN or with other services listening on the same server.
Required:
- MUST treat outbound requests to user-provided URLs as high risk.
- SHOULD allowlist hosts/domains for any user-influenced URL fetch.
- SHOULD block access to localhost/private IP ranges/link-local addresses and cloud metadata endpoints.
- MUST restrict schemes to `http`/`https` (no `file:`, `gopher:`, etc.).
- MUST set client timeouts and restrict redirects.
Insecure patterns:
- `http.Get(r.URL.Query().Get("url"))`
- “URL preview” / “webhook test” endpoints that fetch arbitrary URLs.
Detection hints:
- Search for `http.Get`, `client.Do`, and URL values derived from requests/DB.
- Identify features that fetch remote resources.
Fix:
- Parse URLs strictly; enforce scheme and allowlisted hostnames.
- Resolve DNS and enforce IP-range restrictions (with care for DNS rebinding).
- Set timeouts, disable redirects unless needed, and cap response sizes.
---
### GO-HTTPCLIENT-001: Outbound HTTP clients MUST set timeouts and close bodies
Severity: High (DoS and resource exhaustion)
Required:
- MUST set an overall timeout on `http.Client` usage (or equivalent per-request deadlines via context + transport timeouts).
- MUST ensure `resp.Body.Close()` is called for all successful requests (typically `defer resp.Body.Close()` immediately after error check).
- SHOULD limit response body reads (do not `io.ReadAll` unbounded responses).
- SHOULD restrict redirects for security-sensitive fetches (SSRF, auth flows).
Insecure patterns:
- Using `http.DefaultClient` / `http.Get` for user-influenced destinations with no timeout policy.
- Missing `defer resp.Body.Close()` leading to resource leaks.
- `io.ReadAll(resp.Body)` with no limit.
Detection hints:
- Search for `http.Get(`, `http.Post(`, `client := &http.Client{}` without `Timeout`, `client.Do(` and missing closes.
- Search for `io.ReadAll(resp.Body)`.
Fix:
- Use a configured client with timeouts.
- Always close response bodies.
- Use bounded readers (`io.LimitReader`) for large/untrusted responses.
Notes:
- The net/http package exposes `DefaultClient` as a zero-valued `http.Client`, which can easily lead to “no timeout” behavior unless configured.
---
### GO-REDIRECT-001: Prevent open redirects
Severity: Medium (can be High with auth flows)
Required:
- MUST validate redirect targets derived from untrusted input (`next`, `redirect`, `return_to`).
- SHOULD prefer only same-site relative paths.
- SHOULD fall back to a safe default on validation failure.
Insecure patterns:
- `http.Redirect(w, r, r.URL.Query().Get("next"), http.StatusFound)` with no validation.
Detection hints:
- Search for `http.Redirect(` and check origin of the location.
Fix:
- Allowlist internal paths or known domains.
- Reject absolute URLs unless explicitly needed and allowlisted.
---
### GO-CRYPTO-001: Cryptographic randomness MUST come from crypto/rand
Severity: High (Critical if used for auth/session tokens or keys)
Required:
- MUST use `crypto/rand` for:
- session IDs, password reset tokens, API keys, CSRF tokens, nonces
- encryption keys, signing keys, salts when required
- MUST NOT use `math/rand` for any security-sensitive value.
- SHOULD use built-in helpers that produce appropriately strong tokens when available.
Insecure patterns:
- `math/rand.Seed(time.Now().UnixNano())` followed by token generation for auth or sessions.
- Using UUIDv4-like constructs built from `math/rand`.
Detection hints:
- Search for `math/rand`, `rand.Seed`, `rand.Intn` in code that touches auth/session/token flows.
- Search for custom token generators.
Fix:
- Switch to `crypto/rand` (`rand.Reader`, `rand.Read`, or secure token helpers).
- Ensure sufficient entropy and use URL-safe encoding.
Notes:
- The crypto/rand package provides secure randomness APIs and token generation helpers.
---
### GO-AUTH-001: Password storage MUST use adaptive hashing (bcrypt/argon2id) and safe comparisons
Severity: High
Required:
- MUST hash passwords using an adaptive password hashing function (bcrypt or argon2id).
- MUST NOT store plaintext passwords or reversible encryption of passwords.
- MUST compare secrets in constant time when relevant (tokens, MACs, API keys) to reduce timing leaks.
- SHOULD ensure password policies do not exceed algorithm constraints (e.g., bcrypt has input length limits; handle long passphrases appropriately).
Insecure patterns:
- `sha256(password)` stored as password hash.
- Plaintext password storage.
- Comparing secrets with `==` in timing-sensitive contexts.
Detection hints:
- Search for `sha1`, `sha256`, `md5` used on passwords.
- Search for `bcrypt`/`argon2` usage; if absent, suspect.
- Search for `==` comparisons on tokens/API keys.
Fix:
- Use `bcrypt.GenerateFromPassword` / `CompareHashAndPassword` or argon2id with recommended parameters.
- Use constant-time compare helpers when comparing MACs/tokens.
Notes:
- Go provides bcrypt in `golang.org/x/crypto/bcrypt`, and constant-time comparisons in `crypto/subtle`.
---
### GO-CONC-001: Data races and concurrency hazards MUST be treated as security-relevant
Severity: Medium to High (depends on what races affect)
Required:
- MUST run tests with the race detector (`go test -race`) in CI for security-sensitive services.
- MUST fix detected races; do not suppress without deep justification.
- SHOULD treat shared mutable state in handlers as high risk; enforce synchronization or avoid shared mutability.
Insecure patterns:
- Global maps/slices mutated from multiple goroutines without a mutex.
- Caches or auth/session state stored in globals without concurrency protection.
- Racy access to authorization state (can lead to bypasses or inconsistent enforcement).
Detection hints:
- Search for `var someMap = map[...]...` used in handlers.
- Look for missing `sync.Mutex`, `sync.Map`, channels, or other synchronization.
- Ensure CI includes `-race` and that it runs relevant tests.
Fix:
- Add proper synchronization or redesign to avoid shared mutable state.
- Add race tests and run them continuously.
Notes:
- The Go race detector only finds races that occur in executed code paths; improve test coverage and run realistic workloads with `-race` where feasible.
---
### GO-UNSAFE-001: Use of unsafe/cgo MUST be minimized and audited like memory-unsafe code
Severity: High (Critical in high-risk code paths)
Required:
- SHOULD avoid importing `unsafe` in application code unless absolutely necessary.
- If `unsafe` is used, MUST treat it as “manual memory safety” requiring careful review and test coverage.
- If `cgo` is used, MUST treat the C/C++ boundary as memory-unsafe; apply secure coding practices on the C side and isolate where possible.
Insecure patterns:
- Widespread `unsafe.Pointer` casts in parsing, serialization, auth, or network code.
- `cgo` used for parsing or security boundaries without sandboxing.
Detection hints:
- Search for `import "unsafe"`, `unsafe.Pointer`, `// #cgo`, `import "C"`.
- Prioritize review where unsafe touches untrusted input.
Fix:
- Replace unsafe/cgo usage with safe standard library alternatives where possible.
- Isolate unsafe code in small, well-tested modules with fuzz/race tests.
Notes:
- The unsafe package explicitly provides operations that step around Go’s type safety guarantees.
--------------------------------------------------------------------
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
Toolchain & dependencies:
- `FROM golang:` (Dockerfiles), `go-version:` (CI), `toolchain go` (go.mod), pinned old versions
- `GOSUMDB=off`, `GOINSECURE`, `GONOSUMDB`, `GOPROXY=direct`
- `replace` directives in `go.mod` to forks/paths
- `govulncheck` missing in CI
HTTP server hardening:
- `http.ListenAndServe(`, `ListenAndServeTLS(`, `&http.Server{` with missing timeouts
- `ReadHeaderTimeout: 0`, `ReadTimeout: 0`, `WriteTimeout: 0`, `IdleTimeout: 0`, missing `MaxHeaderBytes`
Body parsing / DoS:
- `io.ReadAll(r.Body)`, `json.NewDecoder(r.Body)` without size cap
- `ParseMultipartForm`, `FormFile`, `multipart.NewReader` without explicit limits
- Missing `http.MaxBytesReader`
Debug exposure:
- `import _ "net/http/pprof"`
- `/debug/pprof`, `/debug/vars`
Templates / XSS / SSTI:
- `text/template` used for HTML output
- `template.HTML(`, `template.JS(`, `template.URL(` with user-controlled data
- `.Parse(` on user-controlled strings
Files:
- `http.ServeFile(` with user path
- `http.FileServer(http.Dir(` pointing at repo root or uploads
- `os.Open(filepath.Join(base, user))` without containment checks
Injection:
- SQL building with `fmt.Sprintf`, string concatenation near `db.Query/Exec`
- `exec.Command("sh","-c", ...)`, `exec.Command("bash","-c", ...)`
SSRF / outbound HTTP:
- `http.Get(userURL)`, `client.Do(req)` where URL comes from request/DB
- Missing client timeout, missing `resp.Body.Close()`, unbounded `io.ReadAll(resp.Body)`
Crypto:
- `math/rand` in token/session generation
- `InsecureSkipVerify: true`
- Password hashing with `sha256`/`md5` instead of bcrypt/argon2
Concurrency:
- Shared maps/slices mutated from handlers without locks
- CI lacking `go test -race`
Always try to confirm:
- data origin (untrusted vs trusted)
- sink type (template/SQL/subprocess/files/http)
- protective controls present (limits, validation, allowlists, middleware, network controls)
--------------------------------------------------------------------
## 6) Sources (accessed 2026-01-28)
Primary Go documentation:
- Go Security Policy — https://go.dev/doc/security/policy
- Go Release History (security fixes in patch releases) — https://go.dev/doc/devel/release
- Go 1.25 Release Notes — https://go.dev/doc/go1.25
- net/http (server timeouts, MaxHeaderBytes, DefaultClient) — https://pkg.go.dev/net/http
- html/template (auto-escaping and trusted-template assumptions) — https://pkg.go.dev/html/template
- crypto/tls (MinVersion defaults, InsecureSkipVerify warnings) — https://pkg.go.dev/crypto/tls
- crypto/rand (secure randomness, token helpers) — https://pkg.go.dev/crypto/rand
- crypto/subtle (constant-time comparisons) — https://pkg.go.dev/crypto/subtle
- os/exec (no shell by default; command execution guidance) — https://pkg.go.dev/os/exec
- unsafe (bypasses type safety) — https://go.dev/src/unsafe/unsafe.go
- net/http/pprof (debug endpoints) — https://pkg.go.dev/net/http/pprof
- cmd/go (module authentication via go.sum/checksum DB; env vars like GOINSECURE) — https://pkg.go.dev/cmd/go
- Module Mirror and Checksum Database Launched (Go blog) — https://go.dev/blog/module-mirror-launch
- govulncheck documentation — https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck
- Go Race Detector documentation — https://go.dev/doc/articles/race_detector
- bcrypt (password hashing) — https://pkg.go.dev/golang.org/x/crypto/bcrypt
- Go vulnerability entry example (multipart resource consumption) — https://pkg.go.dev/vuln/GO-2023-1569
OWASP Cheat Sheet Series (general web security):
- Session Management — https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
- CSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
- SSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
- XSS Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
- HTTP Security Response Headers — https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html
.blackbox/skills/security-best-practices/references/javascript-express-web-server-security.md
+1158
View File
File diff suppressed because it is too large Load Diff
.blackbox/skills/security-best-practices/references/javascript-general-web-frontend-security.md
+747
View File
@@ -0,0 +1,747 @@
# Frontend JavaScript/TypeScript Web Security Spec (Vanilla Browser JS/TS, Modern Browsers)
This document is designed as a **security spec** that supports:
1. **Secure-by-default code generation** for new frontend JavaScript/TypeScript (no specific framework assumed).
2. **Security review / vulnerability hunting** in existing frontend code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
---
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
* MUST NOT request, output, log, hard-code, or commit secrets (API keys intended to be secret, private keys, passwords, OAuth refresh tokens, session tokens, cookies).
Notes:
* Frontend code is inherently observable by end users. If a value must remain secret, it must not be in browser-delivered code.
* If the project uses “public” keys (e.g., publishable analytics keys), they MUST be treated as non-secret and scoped accordingly.
* MUST NOT “fix” security by disabling protections (e.g., weakening CSP with `unsafe-inline`/`unsafe-eval` without justification, removing origin checks for `postMessage`, switching to `innerHTML` for convenience, accepting arbitrary redirects/URLs, or turning off sanitization).
* MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and relevant HTML/CSP/config values that justify the claim.
* MUST treat uncertainty honestly:
* Security headers (CSP, frame-ancestors, etc.) might be set by server/edge/CDN rather than in repo code. If not visible, report as “not visible here; verify at runtime/edge config.” (Also note that `<meta http-equiv=...>` only simulates a subset of headers; don’t assume other security headers exist just because a meta tag exists.) ([MDN Web Docs][1])
---
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new frontend JS/TS code or modify existing code:
* MUST follow every **MUST** requirement in this spec.
* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
* MUST prefer safe-by-default browser APIs and proven libraries over custom security code (especially for HTML sanitization).
* MUST avoid introducing new risky sinks (DOM XSS injection sinks like `innerHTML`, navigation to `javascript:` URLs, dynamic code execution via `eval`/`Function`, unsafe `postMessage`, unsafe third-party script loading, etc.). ([OWASP Cheat Sheet Series][2])
### 1.2 Passive review mode (always on while editing)
While working anywhere in a frontend repo (even if the user did not ask for a security scan):
* MUST “notice” violations of this spec in touched/nearby code.
* SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
* MUST systematically search the codebase for violations of this spec.
* MUST output findings in a structured format (see §2.3).
Recommended audit order:
1. HTML entrypoints (`index.html`, server-rendered templates), script/style includes, and any CSP delivery (header vs meta). ([W3C][3])
2. DOM XSS sinks (`innerHTML`, `document.write`, `insertAdjacentHTML`, event-handler attributes) and their data sources (URL params/hash, storage, postMessage, API responses). ([OWASP Cheat Sheet Series][2])
3. Navigation/redirect handling (`window.location*`, link targets, URL allowlists) including `javascript:` URL hazards. ([MDN Web Docs][4])
4. Cross-origin communication (`postMessage`, iframe embed patterns, sandboxing). ([MDN Web Docs][5])
5. Storage of sensitive data (localStorage/sessionStorage) and assumptions about trust. ([OWASP Cheat Sheet Series][6])
6. Third-party scripts / tag managers / CDNs, and integrity controls (SRI) and policy controls (CSP). ([OWASP Cheat Sheet Series][7])
7. DOM clobbering gadgets and unsafe reliance on `window`/`document` named properties. ([OWASP Cheat Sheet Series][8])
---
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
* URL-derived data: `location.href`, `location.search`, `location.hash`, `document.baseURI`, `new URLSearchParams(location.search)`, routing fragments. ([OWASP Cheat Sheet Series][2])
* DOM content that may include user-controlled markup (comments, profiles, CMS content, markdown-to-HTML output, etc.), especially if inserted dynamically. ([OWASP Cheat Sheet Series][2])
* `postMessage` event data (`event.data`) and metadata (`event.origin`) from other windows/frames. ([MDN Web Docs][5])
* Browser storage: `localStorage`, `sessionStorage`, IndexedDB (contents can be attacker-influenced via XSS or local machine access; never treat as “trusted”). ([OWASP Cheat Sheet Series][6])
* Any data returned from network calls (even if from “your API”), because it may contain stored attacker content that becomes dangerous only when inserted into the DOM. ([OWASP Cheat Sheet Series][2])
### 2.2 Dangerous sink (DOM XSS / code execution sink)
A sink is any API/operation that can execute script or interpret attacker-controlled strings as HTML/JS/URL in a security-sensitive way. High-signal sinks include:
* HTML parsing / insertion: `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`, `document.writeln`. ([OWASP Cheat Sheet Series][2])
* Dynamic code execution: `eval`, `new Function`, `setTimeout("...")`, `setInterval("...")`. ([MDN Web Docs][10])
* Navigation to script-bearing URLs (e.g., `javascript:`) via setters like `Location.href`/`window.location` (and via link `href` if attacker-controlled). ([MDN Web Docs][4])
* Setting event handler attributes from strings, e.g. `setAttribute("onclick", "...")`. ([OWASP Cheat Sheet Series][2])
### 2.3 Required audit finding format
For each issue found, output:
* Rule ID:
* Severity: Critical / High / Medium / Low
* Location: file path + function/class/module + line(s)
* Evidence: the exact code/config snippet
* Impact: what could go wrong, who can exploit it
* Fix: safe change (prefer minimal diff)
* Mitigation: defense-in-depth if immediate fix is hard
* False positive notes: what to verify if uncertain
---
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest baseline that prevents common frontend JS/TS security misconfigurations. Some items are “in repo” (HTML/JS) and some may live at the server/edge.
### 3.1 Content Security Policy (CSP) baseline (SHOULD; MUST for high-risk apps)
* SHOULD deliver CSP via HTTP response headers when possible.
* MAY deliver CSP via an HTML `<meta http-equiv="Content-Security-Policy" ...>` tag when you cannot set headers (e.g., purely static hosting constraints). ([MDN Web Docs][1])
* If using CSP via `<meta http-equiv>`, MUST understand the limitations:
* The policy only applies to content that follows the meta element (so it must appear very early, before any scripts/resources you want governed). ([W3C][3])
* The following directives are **not supported** in a meta-delivered policy and will be ignored: `report-uri`, `frame-ancestors`, and `sandbox`. ([W3C][3])
* “Report-only” CSP cannot be set via a meta element. ([W3C][3])
Practical baseline goals:
* Avoid script sources `unsafe-inline` and `unsafe-eval` (they significantly weaken CSP’s value against XSS). ([MDN Web Docs][10])
* Prefer nonce- or hash-based script policies if you need inline scripts. ([MDN Web Docs][10])
* Consider enabling Trusted Types enforcement where feasible. ([MDN Web Docs][11])
### 3.2 Third-party scripts baseline (SHOULD)
* SHOULD minimize third-party script execution and treat it as equivalent privilege to first-party JS (it runs with your origin’s privileges). ([OWASP Cheat Sheet Series][7])
* SHOULD use Subresource Integrity (SRI) for third-party scripts/styles loaded from CDNs. ([MDN Web Docs][12])
### 3.3 Cross-window communication baseline (SHOULD)
* SHOULD restrict `postMessage` communications to explicit origins, and validate both origin and message shape. ([MDN Web Docs][5])
---
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### JS-XSS-001: Do not inject untrusted HTML into the DOM (avoid `innerHTML` and friends)
Severity: Critical if you can prove attacker-controlled input can reach these APIs; otherwise Medium
Required:
* MUST treat `innerHTML`, `outerHTML`, and `insertAdjacentHTML` as dangerous sinks when their input can contain untrusted data. ([OWASP Cheat Sheet Series][2])
* MUST prefer safe DOM APIs that do not parse HTML:
* `textContent` for text. ([OWASP Cheat Sheet Series][2])
* `document.createElement`, `appendChild`, `setAttribute` for non-event-handler attributes. ([OWASP Cheat Sheet Series][2])
* If HTML insertion is truly required, SHOULD sanitize with a well-reviewed HTML sanitizer and strongly consider enforcing Trusted Types to confine usage to audited code paths. ([MDN Web Docs][11])
Insecure patterns:
* `el.innerHTML = userInput`
* `el.insertAdjacentHTML('beforeend', userInput)`
* `el.outerHTML = userInput`
Detection hints:
* Search for: `.innerHTML`, `.outerHTML`, `insertAdjacentHTML(`.
* Trace the origin of inserted string: URL params/hash, postMessage, storage, API responses, DOM attributes. ([OWASP Cheat Sheet Series][2])
Fix:
* Replace with `textContent` for plain text. ([OWASP Cheat Sheet Series][2])
* For structured UI, build DOM nodes explicitly.
* For “rich text” requirements:
* Sanitize using an allowlist-based sanitizer.
* Prefer returning safe “components” instead of arbitrary HTML strings.
* Use Trusted Types enforcement to ensure only `TrustedHTML` reaches sinks where supported. ([MDN Web Docs][11])
Mitigation:
* Deploy a strict CSP and consider Trusted Types enforcement (`require-trusted-types-for 'script'`). ([MDN Web Docs][10])
False positive notes:
* If the string is provably constant or fully generated from trusted constants, it may be safe. Still prefer safer APIs.
---
### JS-XSS-002: Avoid `document.write` / `document.writeln` (XSS + document clobbering hazards)
Severity: Critical if you can prove attacker-controlled input can reach these APIs; otherwise Medium
Required:
* MUST avoid `document.write()` and `document.writeln()` in production code (they are XSS vectors and can be abused with crafted HTML even if some browsers block injected `<script>` in certain situations). ([MDN Web Docs][13])
* If legacy use is unavoidable, MUST ensure no untrusted input reaches these APIs and SHOULD enforce Trusted Types (`TrustedHTML`) where supported. ([MDN Web Docs][14])
Insecure patterns:
* `document.write(userInput)`
* `document.writeln(getParam('q'))`
Detection hints:
* Search for `document.write(`, `document.writeln(`. ([OWASP Cheat Sheet Series][2])
Fix:
* Replace with DOM manipulation (`createElement`, `appendChild`) or safe text insertion (`textContent`). ([OWASP Cheat Sheet Series][2])
Mitigation:
* Strict CSP + Trusted Types enforcement reduces blast radius if a sink remains. ([MDN Web Docs][10])
---
### JS-XSS-003: Do not use string-to-code execution (`eval`, `new Function`, string timeouts)
Severity: Critical if you can prove attacker-controlled input can reach these APIs; otherwise Medium
Required:
* MUST NOT pass untrusted data to:
* `eval()`
* `new Function(...)`
* `setTimeout("...")` / `setInterval("...")` with string arguments ([MDN Web Docs][10])
* SHOULD avoid these APIs entirely in modern frontend code; refactor to non-eval logic. ([MDN Web Docs][10])
* MUST NOT “fix CSP breakage” by adding `unsafe-eval` unless there is a documented, reviewed justification and compensating controls. ([MDN Web Docs][10])
Insecure patterns:
* `eval(userInput)`
* `new Function("return " + userInput)()`
* `setTimeout(userInput, 0)` where userInput is a string
Detection hints:
* Search for `eval(`, `new Function`, `setTimeout("`, `setInterval("`.
* Also search for construction of code strings used later.
Fix:
* Replace dynamic code with:
* structured data + explicit branching/handlers,
* JSON parsing (`JSON.parse`) instead of `eval` for JSON. ([OWASP Cheat Sheet Series][2])
Mitigation:
* CSP that blocks `eval()`-like APIs by default, and avoid `unsafe-eval`. ([MDN Web Docs][10])
* Consider Trusted Types for controlled cases, but treat it as a hardening layer, not a license to keep eval patterns. ([MDN Web Docs][10])
---
### JS-XSS-004: Do not set event handler attributes from strings (e.g., `setAttribute("onclick", "...")`)
Severity: High
Required:
* MUST NOT use `setAttribute("on…", string)` or similar patterns with untrusted data; this coerces strings into executable code in the event-handler context. ([OWASP Cheat Sheet Series][2])
* SHOULD prefer `addEventListener` with function references.
Insecure patterns:
* `el.setAttribute("onclick", userInput)`
* `el.onclick = userControlledString` (string assignment)
Detection hints:
* Search for `.setAttribute("on`, `.onclick =`, `.onmouseover =`, etc.
* Trace whether RHS can be influenced by URL/hash/storage/postMessage. ([OWASP Cheat Sheet Series][2])
Fix:
* Replace with `addEventListener("click", () => { ... })`.
* If dynamic dispatch is needed, use an allowlisted mapping from identifiers to functions (no string eval). ([OWASP Cheat Sheet Series][2])
---
### JS-URL-001: Sanitize and allowlist URLs before navigation (especially `window.location` / `location.replace`)
Severity: Low (High if you can prove an attacker can fully control the URL)
IMPORTANT: This can cause a lot of false positives. Please perform extra analysis to determine if the url is fully attacker controlled. If not fully attacker controlled, then this is informational at best.
NOTE: It may be important functionality to be able to redirect to any given url. If that is the goal of the feature, then at a minimum, ensure it checks the schema even if the origin is allowed to be anything.
Required:
* MUST treat any assignment to navigation targets as security-sensitive:
* `window.location = ...`
* `location.href = ...`
* `location.assign(...)`
* `location.replace(...)` ([MDN Web Docs][4])
* MUST prevent navigation to `javascript:` URLs (and generally other script-bearing/active schemes), especially when input is derived from URL params, storage, or messages. ([MDN Web Docs][4]). Only allow `http:` and `https:`.
* SHOULD validate/allowlist the destination. A safe baseline is:
* Allow only same-origin relative paths, OR
* Allow only a strict allowlist of origins and protocols (typically `https:` and optionally `http:` for localhost dev). ([OWASP Cheat Sheet Series][8])
Insecure patterns:
* `location.replace(getParam("next"))`
* `window.location = userSuppliedUrl`
* `location.assign(window.redirectTo || "/")` where `redirectTo` can be clobbered or attacker-set ([OWASP Cheat Sheet Series][8])
Detection hints:
* Search for `window.location`, `location.href`, `location.assign`, `location.replace`.
* Search for common redirect parameters: `next`, `returnTo`, `redirect`, `url`, `continue`.
* Search for `javascript:` literal usage. ([MDN Web Docs][4])
Fix:
* Parse and validate with `new URL(value, location.origin)` and then enforce:
* `url.protocol` in `{ "https:" }` (and only include `http:` in explicit dev-only code paths),
* `url.origin` equals `location.origin` for internal redirects, or in a strict allowlist for external redirects,
* optionally allow only specific path prefixes. ([MDN Web Docs][4])
* If validation fails, navigate to a safe default (home/dashboard).
Mitigation:
* Deploy strict CSP and Trusted Types enforcement to reduce the impact of DOM XSS sinks, but note that Trusted Types do not prevent every possible unsafe navigation scenario on their own. ([W3C][15])
False positive notes:
IMPORTANT: This can cause a lot of false positives. Please perform extra analysis to determine if the url is fully attacker controlled. If not fully attacker controlled, then this is informational at best.
* Some apps intentionally support external redirects (SSO, payment flows). Those MUST be allowlisted and documented.
---
### JS-URL-002: Sanitize URLs before inserting into DOM URL contexts (`href`, `src`, etc.)
Severity: Low (High if you can prove an attacker can fully control the URL)
IMPORTANT: This can cause a lot of false positives. Please perform extra analysis to determine if the url is fully attacker controlled. If not fully attacker controlled, then this is informational at best.
Required:
* MUST treat setting URL-bearing DOM attributes/properties as security-sensitive, especially:
* `a.href`, `img.src`, `script.src`, `iframe.src`, `form.action`, `link.href`.
* MUST prevent script-bearing schemes (`javascript:` and other active schemes) when values can be attacker-influenced. ([MDN Web Docs][4])
* SHOULD prefer setting properties (e.g., `a.href = url.toString()`) after parsing and validation, rather than string concatenation.
Insecure patterns:
* `link.href = getParam("u")`
* `el.setAttribute("href", userInput)` without validation
* constructing URLs via concatenation with untrusted pieces
Detection hints:
* Search for `.href =`, `.src =`, `.action =`, `setAttribute("href"`, `setAttribute("src"`.
* Search for `javascript:` / `data:` usage in URLs. ([MDN Web Docs][4])
IMPORTANT: This can cause a lot of false positives. Please perform extra analysis to determine if the url is fully attacker controlled. If not fully attacker controlled, then this is informational at best.
Fix:
* Use `new URL(...)` and validate:
* protocol allowlist
* avoid passing user-provided values into `<script src>` at all (treat as code execution). ([OWASP Cheat Sheet Series][8])
---
### JS-CSP-001: Use CSP; meta delivery is allowed
Severity: Medium to High (depends on threat model; High when handling untrusted content)
NOTE: It is most important to set the CSP's script-src. All other directives are not as important and can generally be excluded for the ease of development.
Required:
* SHOULD deploy a CSP as a major defense-in-depth against XSS. ([MDN Web Docs][10])
* MAY provide CSP via `<meta http-equiv="Content-Security-Policy" ...>` when headers are not available. ([MDN Web Docs][1])
* If CSP is delivered via meta, MUST:
* place it early (before scripts/resources you want governed), and
* not rely on unsupported directives in meta policies (`report-uri`, `frame-ancestors`, `sandbox`). ([W3C][3])
* MUST avoid adding `unsafe-inline` as a “quick fix” for CSP issues unless explicitly required and reviewed (it defeats much of CSP’s purpose). ([MDN Web Docs][10])
* MUST avoid adding `unsafe-eval` unless explicitly required and reviewed (it allows eval-like APIs that are commonly abused). ([MDN Web Docs][10])
Insecure patterns:
* No CSP present anywhere (repo HTML or server/edge) for an app that renders untrusted content.
* CSP includes `script-src 'unsafe-inline'` and/or `script-src 'unsafe-eval'` without strong justification. ([MDN Web Docs][10])
* CSP delivered via meta but includes `frame-ancestors` (it will be ignored in meta). ([W3C][3])
Detection hints:
* Search HTML for `<meta http-equiv="Content-Security-Policy"`.
* Search server/edge configs for `Content-Security-Policy` header.
* If CSP is only in meta, check it appears before any `<script>` tags you want governed. ([W3C][3])
Fix:
* Prefer header-delivered CSP at the server/edge.
* If constrained to meta, keep a strong allowlist CSP and document the limitations; implement clickjacking protections (e.g., `frame-ancestors`) at the server/edge, not in meta. ([W3C][3])
---
### JS-CSP-002: Prefer strict CSP (nonces/hashes); avoid inline/eval patterns in code
Severity: Medium
NOTE: It is most important to set the CSP's script-src. All other directives are not as important and can generally be excluded for the ease of development.
Required:
* SHOULD design frontend code to work under a strict CSP:
* avoid inline scripts and inline event handlers,
* avoid eval-like APIs (see JS-XSS-003),
* allow scripts via nonce or hash when needed. ([MDN Web Docs][10])
Insecure patterns:
* Large amounts of inline script blocks and inline `onclick="..."` handlers.
* Libraries that require `unsafe-eval`.
Detection hints:
* Search for `<script>` blocks with inline code, `onclick="`, `onload="`, etc.
* Search for CSP directives containing `unsafe-inline` or `unsafe-eval`. ([MDN Web Docs][10])
Fix:
* Move inline scripts into external JS files (same-origin).
* Use nonces/hashes for any unavoidable inline blocks. ([MDN Web Docs][10])
---
### JS-TT-001: Use Trusted Types to reduce DOM XSS attack surface (where supported)
Severity: Low
Required:
* SHOULD consider enabling Trusted Types enforcement with CSP `require-trusted-types-for 'script'` to make many DOM XSS sinks reject raw strings. ([MDN Web Docs][11])
* If using Trusted Types, SHOULD also use the CSP `trusted-types` directive to restrict which policies can be created (reduces policy sprawl and improves auditability). ([MDN Web Docs][16])
* MUST keep Trusted Types policy code small, heavily reviewed, and used as the only path to produce trusted values for sinks. ([W3C][15])
Insecure patterns:
* “Trusted Types enabled” but policy simply returns input unchanged (no sanitization/validation).
* Many ad-hoc policies created across the codebase without restriction.
* Belief that Trusted Types alone prevents all unsafe navigations or all XSS classes. (It targets DOM injection sinks; it is not a universal sandbox.) ([W3C][15])
Detection hints:
* Search for CSP directives: `require-trusted-types-for` and `trusted-types`.
* Search code for `trustedTypes.createPolicy(` and inspect policy implementations. ([MDN Web Docs][11])
Fix:
* Add a small set of well-reviewed policies (e.g., `createHTML` that sanitizes).
* Restrict allowed policies via `trusted-types <policyName...>`.
* Migrate sinks to require `TrustedHTML` / `TrustedScriptURL` as appropriate. ([MDN Web Docs][11])
---
### JS-MSG-001: `postMessage` must use strict origin validation and explicit targetOrigin
Severity: Medium (High if dangerous behavior can be triggered via postMessage)
Required:
* When sending messages, MUST set an explicit `targetOrigin` (not `*`) to avoid sending data to an unexpected origin after redirects or window origin changes. ([MDN Web Docs][5])
* When receiving messages, MUST:
* Validate `event.origin` exactly against an allowlist of expected origins (no substring matching). ([OWASP Cheat Sheet Series][6])
* Consider validating `event.source` (expected window reference) when applicable. ([MDN Web Docs][5])
* Validate `event.data` structure (schema/shape) and treat it purely as data (never evaluate it as code and never insert into DOM with `innerHTML`). ([OWASP Cheat Sheet Series][6])
Insecure patterns:
* `otherWindow.postMessage(payload, "*")`
* `window.addEventListener("message", (e) => { doSomething(e.data) })` with no `origin` check
* `if (e.origin.includes("trusted.com"))` (substring checks)
* `el.innerHTML = e.data` ([OWASP Cheat Sheet Series][6])
Detection hints:
* Search for `postMessage(`, `addEventListener("message"`, `onmessage =`.
* Audit all handlers for explicit allowlist checks on `event.origin`. ([OWASP Cheat Sheet Series][6])
Fix:
* Define an allowlist:
* `const ALLOWED = new Set(["https://app.example.com", "https://accounts.example.com"]);`
NOTE: For ease of development, you can use the current page's origin `window.location.origin` as a safe default origin.
* On receive:
* `if (!ALLOWED.has(event.origin)) return;`
* Validate `event.data` with a strict schema and reject unknown/extra fields.
* On send:
* use the exact expected origin string as `targetOrigin`. ([OWASP Cheat Sheet Series][6])
Mitigation:
* Combine with a strict CSP and avoid DOM sinks in message paths. ([MDN Web Docs][10])
---
### JS-STORAGE-001: Web Storage is not a safe place for secrets (and is attacker-influencable)
Severity: Low
Required:
* MUST NOT store sensitive secrets or session identifiers in `localStorage` (or `sessionStorage`) if compromise would matter; a single XSS can exfiltrate everything in storage. ([OWASP Cheat Sheet Series][6])
* MUST treat values read from storage as untrusted input (attackers can load malicious values into storage via XSS). ([OWASP Cheat Sheet Series][6])
* SHOULD prefer server-set cookies with `HttpOnly` for session identifiers (JS cannot set `HttpOnly`, so avoid storing session IDs in JS-accessible storage). ([OWASP Cheat Sheet Series][6])
* SHOULD avoid hosting multiple unrelated apps on the same origin if they rely on storage separation (storage is origin-wide). ([OWASP Cheat Sheet Series][6])
Insecure patterns:
* `localStorage.setItem("access_token", token)`
* `localStorage.setItem("session", sessionId)`
* Assuming `localStorage` is “trusted because same-origin.”
Detection hints:
* Search for `localStorage.getItem`, `localStorage.setItem`, `sessionStorage.*`.
* Flag storage keys named `token`, `jwt`, `session`, `auth`, `refresh`. ([OWASP Cheat Sheet Series][6])
Fix:
* Use server-managed sessions or short-lived tokens delivered and rotated securely, with careful XSS defenses (CSP/Trusted Types) and minimal JS exposure.
* If storage must be used for non-sensitive state, keep it non-auth and validate/escape before use.
---
### JS-SUPPLY-001: Third-party JavaScript is a major supply-chain risk; minimize and control it
Severity: Low
Required:
* MUST treat third-party JS as equivalent to first-party JS in privilege (it can execute arbitrary code in your origin and access DOM data). ([OWASP Cheat Sheet Series][7])
* SHOULD minimize third-party scripts and prefer:
* self-hosting / script mirroring,
* strict CSP allowlists,
* SRI for any CDN-hosted scripts,
* ongoing monitoring for unexpected changes. ([OWASP Cheat Sheet Series][7])
Insecure patterns:
* Loading arbitrary remote scripts from many vendors without review.
* Using tag managers that can dynamically inject scripts with no integrity controls.
* Allowing scripts from broad wildcards in CSP (e.g., `script-src *`). ([MDN Web Docs][10])
Detection hints:
* Search HTML for `<script src="https://...">` and `tag manager` snippets.
* Search CSP `script-src` sources for wildcards or overly broad domains.
* Search for dynamic script injection: `document.createElement("script")`, `script.src = ...`, `appendChild(script)`. ([OWASP Cheat Sheet Series][8])
Fix:
* Remove unnecessary third-party tags.
* Self-host or mirror scripts where possible.
* Lock down CSP `script-src` to the smallest set of trusted sources.
* Add SRI for CDN scripts/styles. ([OWASP Cheat Sheet Series][7])
---
### JS-SRI-001: Use Subresource Integrity (SRI) for third-party scripts/styles
Severity: Low
Required:
* SHOULD use SRI to ensure browsers only load third-party resources if they match an expected cryptographic hash. ([MDN Web Docs][12])
* MUST update SRI hashes whenever the underlying resource changes (pin versions; avoid “latest” URLs).
Insecure patterns:
* `<script src="https://cdn.example.com/lib.js"></script>` with no `integrity`.
* Loading `latest` or unpinned third-party resources.
Detection hints:
* Search for `<script src="https://` and `<link rel="stylesheet" href="https://` without `integrity=`.
* Check whether `integrity` is present and uses strong hashes (sha256/384/512 are typical). ([MDN Web Docs][12])
Fix:
* Add `integrity="sha384-..."` (or appropriate) and ensure proper CORS mode where needed.
* Prefer self-hosting critical libraries.
---
### FS-DOMC-001: Prevent DOM clobbering (avoid relying on `window`/`document` named properties)
Severity: Medium to High (can become Critical if it enables script loading or `javascript:` navigation)
Required:
* MUST NOT rely on implicit global variables or `window.someName` / `document.someName` lookups that can be clobbered by injected HTML elements with matching `id`/`name`. ([OWASP Cheat Sheet Series][8])
* MUST avoid patterns like `let x = window.redirectTo || "/safe"; location.assign(x);` where `redirectTo` could be clobbered to an `<a>` element whose `href` is attacker-controlled (including `javascript:`). ([OWASP Cheat Sheet Series][8])
* SHOULD use explicit variable declarations, local scope, and explicit DOM queries (`getElementById`) rather than named property access. ([OWASP Cheat Sheet Series][8])
* If the app inserts user-controlled markup (even sanitized), SHOULD ensure sanitization strategies consider `id`/`name` collisions. ([OWASP Cheat Sheet Series][8])
Insecure patterns:
* `const cfg = window.config || {};` used for security-sensitive URLs.
* `const redirect = window.redirectTo || "/"; location.assign(redirect);` ([OWASP Cheat Sheet Series][8])
* Loading scripts from `window.*` config values without strict validation.
Detection hints:
* Search for `window.` and `document.` used as config stores (especially `||` fallback patterns).
* Search for usage of `location.assign/replace` with variables that come from `window`/`document` properties.
* Search for dynamic script creation (`createElement('script')`) where `.src` comes from a non-local variable. ([OWASP Cheat Sheet Series][8])
Fix:
* Store config in module-scoped constants (not on `window`/`document`) and pass it explicitly.
* Validate any URL-like config with protocol/origin allowlists (see FEJS-URL-001). ([OWASP Cheat Sheet Series][8])
* Consider hardening: sanitization, CSP, and (in limited cases) freezing sensitive objects, but treat these as defense-in-depth, not a substitute for safe coding patterns. ([OWASP Cheat Sheet Series][8])
---
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
* DOM XSS sinks:
* `.innerHTML`, `.outerHTML`, `insertAdjacentHTML(`
* `document.write(`, `document.writeln(` ([OWASP Cheat Sheet Series][2])
* Dangerous navigation / URL sinks:
* `window.location`, `location.href`, `location.assign`, `location.replace`
* `javascript:` literals (and other suspicious schemes like `data:text/html`) ([MDN Web Docs][4])
* String-to-code execution:
* `eval(`, `new Function`, `setTimeout("`, `setInterval("` ([MDN Web Docs][10])
* Event-handler string injection:
* `.setAttribute("on`, `.onclick =`, `.onload =` with strings ([OWASP Cheat Sheet Series][2])
* `postMessage`:
* `postMessage(` with `"*"` as targetOrigin
* `addEventListener("message"` without strict `event.origin` allowlist checks ([MDN Web Docs][5])
* Storage:
* `localStorage.setItem(` / `getItem(`, `sessionStorage.*`
* keys containing `token`, `jwt`, `session`, `auth`, `refresh` ([OWASP Cheat Sheet Series][6])
* CSP and related:
* `Content-Security-Policy` header config (server/edge)
* `<meta http-equiv="Content-Security-Policy" ...>`
* CSP containing `unsafe-inline` or `unsafe-eval`
* `require-trusted-types-for` / `trusted-types` directives ([MDN Web Docs][1])
* Third-party scripts:
* `<script src="https://...">` without `integrity=`
* Tag manager snippets and dynamic script injection code paths ([MDN Web Docs][12])
* DOM clobbering gadgets:
* `window.<name> || ...` and `document.<name> || ...` patterns
* security-sensitive usage of `window`/`document` properties as config sources ([OWASP Cheat Sheet Series][8])
Always try to confirm:
* data origin (untrusted vs trusted),
* sink type (HTML parse, navigation, code execution, message handling, storage),
* protective controls present (CSP, Trusted Types, sanitizers, strict allowlists, schema validation).
---
## 6) Sources (accessed 2026-01-27)
Primary standards / platform docs:
* W3C Content Security Policy Level 2 (HTML `<meta>` delivery restrictions; unsupported directives in meta CSP): `https://www.w3.org/TR/CSP2/` ([W3C][3])
* MDN: CSP Guide (strict CSP, nonces/hashes, `unsafe-inline`/`unsafe-eval`, eval blocking): `https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP` ([MDN Web Docs][10])
* MDN: `<meta http-equiv>` (CSP via meta and warning about meta-based security headers): `https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/http-equiv` ([MDN Web Docs][1])
* MDN: `frame-ancestors` (and note it’s not supported in `<meta>`): `https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors` ([MDN Web Docs][18])
DOM XSS and dangerous sinks:
* OWASP: DOM Based XSS Prevention Cheat Sheet (dangerous sinks + safe patterns like `textContent`): `https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][2])
* MDN: `innerHTML` (security considerations): `https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML` ([MDN Web Docs][19])
* MDN: `insertAdjacentHTML` (security considerations): `https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML` ([MDN Web Docs][20])
* MDN: `document.write()` / `document.writeln()` (security considerations): `https://developer.mozilla.org/en-US/docs/Web/API/Document/write` and `https://developer.mozilla.org/en-US/docs/Web/API/Document/writeln` ([MDN Web Docs][13])
URL scheme hazards:
* MDN: `javascript:` URLs (execution on navigation; discouraged; references `window.location`): `https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/javascript` ([MDN Web Docs][4])
Trusted Types:
* W3C: Trusted Types spec (DOM XSS sinks include `Element.innerHTML` and `Location.href` setters; goals and limitations): `https://www.w3.org/TR/trusted-types/` ([W3C][15])
* MDN: `require-trusted-types-for` directive: `https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for` ([MDN Web Docs][11])
* MDN: `trusted-types` directive: `https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types` ([MDN Web Docs][16])
Cross-window messaging:
* MDN: `window.postMessage` (security guidance: specify targetOrigin; validate origin): `https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage` ([MDN Web Docs][5])
* OWASP: HTML5 Security Cheat Sheet (Web Messaging guidance: explicit origin, strict checks, no `innerHTML`): `https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][6])
Third-party scripts and integrity:
* OWASP: Third Party JavaScript Management Cheat Sheet (risks and mitigations including SRI/mirroring): `https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][7])
* MDN: Subresource Integrity overview: `https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity` ([MDN Web Docs][12])
* W3C: Subresource Integrity spec: `https://www.w3.org/TR/sri-2/` ([W3C][21])
DOM clobbering:
* OWASP: DOM Clobbering Prevention Cheat Sheet (named property access risk; example attacks involving `location.assign` and `javascript:`): `https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][8])
[1]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/http-equiv "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/meta/http-equiv"
[2]: https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html"
[3]: https://www.w3.org/TR/CSP2/ "Content Security Policy Level 2"
[4]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/javascript "javascript: URLs - URIs | MDN"
[5]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage "https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage"
[6]: https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html"
[7]: https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html"
[8]: https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/DOM_Clobbering_Prevention_Cheat_Sheet.html"
[9]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener"
[10]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP "https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP"
[11]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for"
[12]: https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity "https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity"
[13]: https://developer.mozilla.org/en-US/docs/Web/API/Document/write "https://developer.mozilla.org/en-US/docs/Web/API/Document/write"
[14]: https://developer.mozilla.org/en-US/docs/Web/API/Document/writeln "https://developer.mozilla.org/en-US/docs/Web/API/Document/writeln"
[15]: https://www.w3.org/TR/trusted-types/ "https://www.w3.org/TR/trusted-types/"
[16]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/trusted-types"
[18]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/frame-ancestors"
[19]: https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML "https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML"
[20]: https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML "https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML"
[21]: https://www.w3.org/TR/sri-2/ "https://www.w3.org/TR/sri-2/"
.blackbox/skills/security-best-practices/references/javascript-jquery-web-frontend-security.md
+678
View File
@@ -0,0 +1,678 @@
# jQuery Frontend Security Spec (jQuery 4.0.x, modern browsers)
This document is designed as a **security spec** that supports:
1. **Secure-by-default code generation** for new jQuery-based frontend code.
2. **Security review / vulnerability hunting** in existing jQuery-based code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
---
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
* MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session tokens, refresh tokens, CSRF tokens, session cookies).
* MUST treat the browser as an attacker-controlled environment:
* Frontend checks (UI gating, “disable button”, hidden fields, client-side validation) MUST NOT be treated as authorization or a security boundary.
* Server-side authorization and validation MUST exist even if frontend is “correct”.
* MUST NOT “fix” security by disabling protections (e.g., relaxing CSP to allow `unsafe-inline`, enabling JSONP “because it works”, adding broad CORS, disabling sanitization, suppressing security checks).
* MUST provide evidence-based findings during audits: cite file paths, code snippets, and relevant configuration values.
* MUST treat uncertainty honestly: if a protection might exist at the edge (CDN/WAF/reverse proxy headers like CSP), report it as “not visible in repo; verify at runtime/config”.
---
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new jQuery code or modify existing jQuery code:
* MUST follow every **MUST** requirement in this spec.
* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
* MUST prefer safe-by-default patterns: text insertion, DOM node construction, allowlists, and proven sanitization libraries over custom escaping.
* MUST avoid introducing new risky sinks (HTML string building, dynamic script loading, JSONP, inline script/event-handler attributes, unsafe URL assignment, unsafe object merging).
### 1.2 Passive review mode (always on while editing)
While working anywhere in a repo that uses jQuery (even if the user did not ask for a security scan):
* MUST “notice” violations of this spec in touched/nearby code.
* SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
* MUST systematically search the codebase for violations of this spec.
* MUST output findings in the structured format (see §2.3).
Recommended audit order:
1. jQuery sourcing, versions, and dependency hygiene (script tags, lockfiles, CDN usage, SRI).
2. CSP / Trusted Types / security headers posture (in repo and at runtime if observable).
3. DOM XSS: untrusted sources → jQuery sinks (`.html`, `.append`, `$("<…>")`, `.load`, etc.).
4. Script execution sinks: JSONP, `dataType:"script"`, `$.getScript`, dynamic `<script>` insertion.
5. URL/attribute assignment (`href`, `src`, `style`, `on*` attributes).
6. Prototype pollution / unsafe object merging (`$.extend` patterns).
7. AJAX auth patterns + CSRF for cookie-based sessions.
8. Third-party plugins and untrusted content rendering paths (comments, WYSIWYG, markdown-to-HTML).
---
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
* Any data from the server that originates from users (user profiles, comments, “display name”, rich text, filenames).
* Data from third-party APIs or services.
* Browser-controlled sources:
* `location.href`, `location.search`, `location.hash`
* `document.URL`, `document.baseURI`, `document.referrer`
* `window.name`
* `localStorage` / `sessionStorage`
* `postMessage` event data (unless strict origin and schema validation exists)
* Any DOM content that could have been injected previously (stored XSS)
### 2.2 High-risk “sinks” in jQuery contexts
A sink is a code path where untrusted input can become interpreted as executable code or HTML.
Key jQuery sink categories:
* HTML insertion / parsing:
* DOM manipulation methods that accept HTML strings such as `.html()`, `.append()`, and related methods (see CVE notes below). ([NVD][1])
* `$(htmlString)` (when the argument can be interpreted as HTML markup).
* `jQuery.parseHTML(html, …, keepScripts)` especially with `keepScripts=true`. ([jQuery API][2])
* `.load(url)` (loads HTML into DOM; has special script execution behavior). ([jQuery API][3])
* Script execution / dynamic code loading:
* `$.getScript()` / `$.ajax({ dataType: "script" })` (executes fetched JavaScript). ([jQuery API][4])
* JSONP (`dataType: "jsonp"` or implicit JSONP behavior) (executes remote JavaScript as a response). ([jQuery API][5])
* `eval`, `new Function`, `setTimeout("…")`, `setInterval("…")`, `$.globalEval` (if present)
* Dangerous attribute assignment:
* Assigning untrusted strings to `href`, `src`, `srcdoc`, `style`, or event-handler attributes (`onload`, `onclick`, etc.)
* `javascript:` URLs are particularly dangerous and discouraged. ([MDN Web Docs][6])
### 2.3 Required audit finding format
For each issue found, output:
* Rule ID:
* Severity: Critical / High / Medium / Low
* Location: file path + function/component + line(s)
* Evidence: the exact code/config snippet
* Impact: what could go wrong, who can exploit it
* Fix: safe change (prefer minimal diff)
* Mitigation: defense-in-depth if immediate fix is hard
* False positive notes: what to verify if uncertain
---
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common jQuery-related security failures.
### 3.1 Use a supported, patched jQuery version (MUST)
* MUST use a supported jQuery major version and keep it updated.
* As of 2026-01-27, the jQuery project ships jQuery 4.0.0 as the latest major release. ([blog.jquery.com][7])
* If you must support very old browsers (notably IE < 11), jQuery 4 does not support them and you may need to stay on jQuery 3.x; treat this as a higher risk posture and patch aggressively. ([blog.jquery.com][7])
### 3.2 Load jQuery safely (MUST)
* MUST load jQuery only from:
* Your own build pipeline (bundled via npm/yarn + lockfile), or
* The official jQuery CDN / a trusted CDN with Subresource Integrity (SRI) enabled.
* If loading from a CDN, SHOULD use SRI (`integrity`) and correct `crossorigin` settings; the jQuery project explicitly supports and recommends SRI on its CDN. (Retrieved from [jquery.com][8])
### 3.3 CSP + Trusted Types (SHOULD, and MUST where available/required by policy)
* SHOULD deploy a Content Security Policy (CSP) that reduces XSS impact (especially `script-src` restrictions and avoiding `unsafe-inline`). If not done through HTTP server, this can be done through the `<meta http-equiv="Content-Security-Policy" content="...">` tag. ([OWASP Cheat Sheet Series][9]) NOTE: It is most important to set the CSP's script-src. All other directives are not as important and can generally be excluded for the ease of development.
* SHOULD consider Trusted Types as a strong defense-in-depth against DOM XSS. ([W3C][10])
* If you deploy the CSP directive `require-trusted-types-for`, then code MUST route DOM-injection through Trusted Types policies. ([MDN Web Docs][11])
* Note: jQuery 4.0 explicitly added Trusted Types support so that TrustedHTML can be used with jQuery manipulation methods without violating `require-trusted-types-for`. ([blog.jquery.com][7])
### 3.4 Security headers and cookie posture (defense in depth; SHOULD)
Even though these are typically set server-side, they materially reduce the blast radius of jQuery-related mistakes. However if the context is only the frontend web application, these cannot be acted on.
* SHOULD set common security headers (CSP, `X-Content-Type-Options: nosniff`, clickjacking protection via `frame-ancestors` / `X-Frame-Options`, `Referrer-Policy`). ([OWASP Cheat Sheet Series][12])
* SHOULD avoid storing long-lived secrets/tokens in places accessible to JavaScript (like `localStorage`) unless the threat model explicitly accepts “XSS == account takeover”. This is not jQuery-specific, but jQuery-heavy DOM manipulation increases the chance of DOM XSS regressions; reduce the payoff.
---
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### JQ-SUPPLY-001: jQuery MUST be patched; do not run known vulnerable versions
Severity: Medium (High if internet-facing app AND version is known-vulnerable)
NOTE: Before performing an upgrade, get concent from the user and try to understand if they have reasons to keep it back. Upgrading can break applications in unexpected ways. Report and recommend upgrades rather than just performing them.
Required:
* MUST NOT use jQuery versions with known high-impact vulnerabilities when a patched version exists.
* MUST upgrade past:
* CVE-2019-11358 (prototype pollution in jQuery before 3.4.0). ([NVD][13])
* CVE-2020-11022 / CVE-2020-11023 (XSS risks in DOM manipulation methods when handling untrusted HTML; patched in 3.5.0). ([NVD][1])
Insecure patterns:
* Script tags or package manifests referencing old jQuery (e.g., `jquery-1.*`, `jquery-2.*`, `jquery-3.3.*`, `jquery-3.4.*`, `jquery-3.4.1`, etc.).
* Bundled vendor directories containing old minified jQuery without an upgrade path.
Detection hints:
* Search HTML/templates for `jquery-` and parse version strings.
* Check `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`.
* Check `vendor/`, `public/`, `static/`, `assets/`, `wwwroot/` for `jquery*.js`.
Fix:
* Upgrade to current jQuery (prefer latest stable major; as of 2026-01-27, 4.0.0 is current). ([blog.jquery.com][7])
* If upgrade is constrained, at minimum upgrade beyond the CVE thresholds and add compensating controls (strong CSP, strict sanitization, remove risky APIs like JSONP, remove deep-extend of untrusted objects).
Notes:
* If a product requirement forces old versions, report as “accepted risk requiring compensating controls”.
---
### JQ-SUPPLY-002: Third-party script loading SHOULD use integrity and trusted origins
Severity: High
Required:
* MUST load jQuery and plugins only from trusted origins.
* If loaded from CDN, SHOULD use SRI (`integrity`) and correct `crossorigin` handling. ([jquery.com][8])
Insecure patterns:
* `<script src="https://…/jquery.min.js"></script>` with no `integrity`.
* Loading jQuery from random third-party CDNs without an explicit trust decision.
Detection hints:
* Scan HTML for `<script src=` and check for `integrity=` + `crossorigin=`.
* Identify dynamic script insertion with untrusted URLs (see JQ-EXEC-001).
Fix:
* Prefer bundling via npm + lockfile.
* If using CDN, copy official script tag (jQuery CDN supports SRI). ([jquery.com][8])
Note: If unable to get the correct SRI tag, skip this step but tell the user. If you end up using the wrong one the app will not function. In that case remove it and inform the user.
---
### JQ-XSS-001: Untrusted data MUST NOT be inserted as HTML via jQuery DOM-manipulation methods
Severity: High (if attacker-controlled content reaches these sinks)
Required:
* MUST treat any HTML string insertion as a code execution boundary.
* MUST use safe alternatives for untrusted text:
* `.text(untrusted)` (text, not HTML). ([jQuery API][14])
* `.val(untrusted)` for form fields. ([jQuery API][15])
* Create elements and set text/attributes safely instead of concatenating HTML strings.
Insecure patterns (examples):
* `$(selector).html(untrusted)`
* `$(selector).append(untrusted)`
* `$(selector).before(untrusted)` / `.after(untrusted)` / `.replaceWith(untrusted)` / `.wrap(untrusted)` (and similar)
* Building markup: `"<div>" + untrusted + "</div>"` then passing to jQuery
Detection hints:
* Grep for: `.html(`, `.append(`, `.prepend(`, `.before(`, `.after(`, `.replaceWith(`, `.wrap(`, `.wrapAll(`, `.wrapInner(`
* Trace dataflow into these calls from sources in §2.1.
Fix:
* Replace with `.text()` / `.val()` or node construction:
* `const $el = $("<span>").text(untrusted); container.append($el);`
* If the output must contain limited markup, see JQ-XSS-002 (sanitization).
Notes:
* Older jQuery versions had additional edge cases even when attempting sanitization; patched in 3.5.0+. Still: never rely on “string sanitization” alone—prefer structured creation or proven sanitizers. ([GitHub][16])
---
### JQ-XSS-002: If rendering user-controlled HTML is required, it MUST be sanitized with a proven HTML sanitizer
Severity: Medium (High if rich HTML is attacker-controlled and sanitizer is weak/misconfigured)
Required:
* MUST NOT “roll your own” HTML sanitizer with regexes.
* If user-controlled HTML must be displayed (e.g., rich text comments), MUST sanitize using a well-maintained HTML sanitizer and a restrictive allowlist.
* DOMPurify is a common choice; use conservative configuration and keep it updated. ([GitHub][17])
* Where available, MAY consider the browser HTML Sanitizer API (note: limited browser availability). ([MDN Web Docs][18])
* SHOULD pair sanitization with CSP and, where feasible, Trusted Types for defense in depth. ([OWASP Cheat Sheet Series][9])
Insecure patterns:
* Regex-based “strip `<script>`” or “escape `<`” attempts followed by `.html()` insertion.
* DOMPurify (or similar) configured to allow overly broad tags/attributes, or configuration that’s not reviewed.
Detection hints:
* Search for “sanitize” helper functions, regex replacing `<`/`>` patterns, or “allow all tags” configs.
* Identify features that render user-generated “rich text” or “custom HTML”.
* Check if sanitizer results are inserted with `.html()` or equivalent sinks.
Fix:
* Introduce a sanitizer with strict allowlist.
* Centralize the “sanitize then inject” pattern into a single reviewed module.
* Add regression tests covering representative malicious inputs (don’t store payloads in logs or telemetry).
False positive notes:
* If content is guaranteed trusted (e.g., compiled templates shipped by you), document the trust boundary and why it is not attacker-controlled.
---
### JQ-XSS-003: `$(untrustedString)` and `jQuery.parseHTML` MUST NOT process attacker-controlled markup
Severity: High (if attacker-controlled)
Required:
* MUST NOT pass attacker-controlled strings to `$()` when they might be interpreted as HTML.
* MUST treat `jQuery.parseHTML(html, …, keepScripts)` as a high-risk primitive; keepScripts MUST be `false` for any untrusted input. ([jQuery API][2])
Insecure patterns:
* `const $node = $(untrusted);`
* `$.parseHTML(untrusted, /* context */, true)` (scripts preserved)
Detection hints:
* Search for `$(` calls where the argument is not a static selector or static markup.
* Search for `$.parseHTML(` and inspect the `keepScripts` argument.
Fix:
* Use DOM creation with constant tag names and `.text()` for untrusted values.
* If parsing HTML is necessary, sanitize first (JQ-XSS-002) and keep scripts disabled.
---
### JQ-XSS-004: `.load()` MUST be treated as an HTML+script injection surface
Severity: Medium (High if URL/content is attacker-controlled)
Required:
* MUST NOT use `.load()` with attacker-controlled URLs or attacker-controlled HTML fragments.
* MUST understand jQuery `.load()` script behavior:
* Without a selector in the URL, content is passed to `.html()` before scripts are removed, which can execute scripts. ([jQuery API][3])
* SHOULD prefer `fetch()`/XHR to retrieve data, then render with safe DOM creation or sanitize explicitly.
Insecure patterns:
* `$("#target").load(untrustedUrl)`
* `$("#target").load("/path?param=" + untrusted)`
Detection hints:
* Search for `.load(` across JS/TS files.
* Identify whether a selector is appended to the URL (the behavior differs). ([jQuery API][3])
* Trace whether the URL can be influenced by user input.
Fix:
* Replace `.load()` with:
* `fetch()` to retrieve JSON, then render via `.text()` / node construction, or
* `fetch()` to retrieve HTML, sanitize it, then inject.
* If `.load()` must remain, ensure the URL is constant or strictly allowlisted and the returned content is trusted.
---
### JQ-EXEC-001: Dynamic script execution and script fetching MUST NOT be reachable from untrusted input
Severity: High
Required:
* MUST NOT fetch-and-execute scripts from untrusted or user-influenced URLs.
* MUST treat these as code execution primitives:
* `$.getScript(url)` executes the fetched script in the global context. ([jQuery API][4])
* `$.ajax({ dataType: "script" })` and other script-typed requests that execute responses.
* SHOULD remove these patterns unless there is a strong, reviewed justification.
Insecure patterns:
* `$.getScript(untrustedUrl)`
* `$.ajax({ url: untrustedUrl, dataType: "script" })`
* Dynamic `<script src=...>` injection where `src` is derived from untrusted input.
Detection hints:
* Search for `getScript(`, `dataType: "script"`, `globalEval`, `eval`, `new Function`.
* Look for “plugin loader” or “theme loader” features that accept URLs.
Fix:
* Bundle scripts at build time.
* If runtime-loading is required, restrict to allowlisted, versioned, integrity-checked assets (and ideally still avoid runtime code loading).
---
### JQ-AJAX-001: JSONP MUST be disabled unless the endpoint is fully trusted (and even then, avoid)
Severity: Medium (High if attacker can influence URL/endpoint)
Required:
* MUST NOT use JSONP for untrusted endpoints because it executes JavaScript responses.
* When using `$.ajax`, MUST explicitly disable JSONP for non-fully-trusted targets; jQuery’s own docs recommend setting `jsonp: false` “for security reasons” if you don’t trust the target. ([jQuery API][5])
* SHOULD prefer CORS with JSON (`dataType: "json"`) and explicit origin allowlists server-side.
Insecure patterns:
* `dataType: "jsonp"`
* URLs containing `callback=?` or patterns that trigger JSONP behavior. callback arguments are historically XSS vectors.
* `$.get(untrustedUrl)` without pinning `dataType` and disabling JSONP (risk depends on options and jQuery behavior)
Detection hints:
* Search for `jsonp`, `dataType: "jsonp"`, `callback=?`.
* Search for cross-domain AJAX where the URL is not hard-coded or allowlisted.
Fix:
* Use JSON over HTTPS with CORS configured server-side.
* Set:
* `dataType: "json"`
* `jsonp: false` (defense in depth when URL might be ambiguous) ([jQuery API][5])
---
### JQ-AJAX-002: State-changing AJAX requests using cookie auth MUST be CSRF-protected
Severity: High
NOTE: This only matters when using cookie based auth. If the request use Authorization header, there is no CSRF potential.
Required:
* If authentication uses cookies, MUST protect state-changing requests (POST/PUT/PATCH/DELETE) against CSRF.
* SHOULD use server-verified CSRF tokens; for AJAX calls, tokens are commonly sent in a custom header. ([OWASP Cheat Sheet Series][19])
* MUST NOT treat “it’s an AJAX request” as CSRF protection by itself.
Insecure patterns:
* `$.post("/transfer", {...})` or `$.ajax({ method: "POST", ... })` with cookie auth and no CSRF token/header.
* “CSRF protection” that only checks for `X-Requested-With` (defense-in-depth only, not primary).
Detection hints:
* Enumerate state-changing AJAX calls and locate whether they include CSRF tokens.
* Identify how the server expects CSRF validation (meta tag, cookie-to-header double submit, synchronizer token, etc.).
Fix:
* Add CSRF token inclusion in a centralized place, e.g., `$.ajaxSetup({ headers: { "X-CSRF-Token": token } })`, and ensure server verifies.
* Follow OWASP CSRF guidance for token properties and validation. ([OWASP Cheat Sheet Series][19])
False positive notes:
* If auth is not cookie-based (e.g., Authorization header bearer token) CSRF risk is different; verify actual auth mechanism.
---
### JQ-ATTR-001: Untrusted values MUST NOT be written into dangerous attributes without validation/allowlisting
Severity: Low (High for events like onclick)
Required:
* MUST validate/allowlist URLs written into `href`, `src`, `action`, etc.
* MUST block dangerous schemes; `javascript:` URLs are discouraged because they can execute code. ([MDN Web Docs][6])
* MUST NOT set event-handler attributes (`onclick`, `onerror`, etc.) from strings.
* SHOULD avoid writing untrusted strings into `style` attributes; prefer toggling predefined CSS classes.
Insecure patterns:
* `$("a").attr("href", untrustedUrl)`
* `$("img").attr("src", untrustedUrl)`
* `$(el).attr("style", untrustedCss)`
* `$(el).attr("onclick", untrustedJs)`
Detection hints:
* Search for `.attr("href"`, `.attr("src"`, `.attr("style"`, `.prop("href"`, `.prop("src"`.
* Trace whether inputs come from URL params, server JSON, DOM, or storage.
Fix:
* Parse and validate URLs with `new URL(value, location.origin)` and allowlist protocols (`https:` etc.) and hostnames when needed.
* For navigation targets, prefer relative paths you construct rather than full URLs.
* Replace `style` strings with `addClass/removeClass` using predefined class names.
---
### JQ-SELECTOR-001: User-controlled selector fragments MUST be escaped with `jQuery.escapeSelector`
Severity: Medium (can become High if it enables wrong-element selection in security-relevant UI)
Required:
* If you must select by an ID/class that can contain special CSS characters, SHOULD use `jQuery.escapeSelector()` (available in jQuery 3.0+). ([jQuery API][20])
* MUST NOT concatenate raw attacker-controlled strings into selector expressions.
Insecure patterns:
* `$("#" + untrustedId)`
* `$("[data-id='" + untrusted + "']")` (especially without strict quoting/escaping)
Detection hints:
* Search for `"#" +`, `". " +`, or template strings used inside `$(` selectors.
* Look for “select by user-supplied id”.
Fix:
* `$("#" + $.escapeSelector(untrustedId))` ([jQuery API][20])
* Prefer stable internal IDs over user-derived selectors.
Notes:
* This is often “robustness”, but it can become security-relevant if incorrect selection causes UI to reveal/modify the wrong data or skip security-related prompts.
---
### JQ-PROTOTYPE-001: Do not deep-merge untrusted objects; prevent prototype pollution
Severity: Medium
Required:
* MUST NOT deep-merge (`$.extend(true, …)`) attacker-controlled objects into application objects without filtering dangerous keys.
* MUST ensure jQuery is >= 3.4.0 to avoid CVE-2019-11358 prototype pollution behavior. ([NVD][13])
Insecure patterns:
* `$.extend(true, target, untrustedObj)`
* `$.extend(true, {}, defaults, untrustedObj)` where untrustedObj comes from URL/JSON/storage
Detection hints:
* Search for `$.extend(true` and inspect sources of merged objects.
* Search for “merge options” / “apply config” patterns using untrusted JSON.
Fix:
* Prefer:
* Shallow merges with an allowlisted set of keys, or
* A safe merge helper that explicitly rejects `__proto__`, `prototype`, `constructor`, and nested occurrences.
* Keep jQuery patched.
---
### JQ-CSP-001: CSP and Trusted Types SHOULD be used to make DOM XSS harder to introduce and exploit
Severity: Medium
Required:
* SHOULD deploy CSP as defense-in-depth against XSS. ([OWASP Cheat Sheet Series][9])
* If enabling Trusted Types (`require-trusted-types-for`), MUST ensure DOM injection goes through Trusted Types policies. ([MDN Web Docs][11])
* When using jQuery 4, SHOULD take advantage of its Trusted Types support (TrustedHTML inputs). ([blog.jquery.com][7])
Insecure patterns:
* “Fixing” a jQuery feature by weakening CSP (`script-src 'unsafe-inline'` / `'unsafe-eval'`) without a compensating plan.
* No CSP on applications that render user content or manipulate DOM heavily.
Detection hints:
* Look for CSP headers (server configs, framework middleware, meta tags).
* If not visible in repo, flag as “verify at edge/runtime”.
Fix:
* Add CSP incrementally; start by eliminating inline scripts and inline event handlers, then tighten `script-src`.
* Add Trusted Types where supported and feasible.
---
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
* jQuery version / sourcing:
* `jquery-*.js` in `vendor/` or `static/`
* `package.json` dependency `jquery` pinned to old versions
* CDN script tags lacking `integrity`/`crossorigin` ([jquery.com][8])
* HTML injection sinks (DOM XSS):
* `.html(`, `.append(`, `.prepend(`, `.before(`, `.after(`, `.replaceWith(`, `.wrap(`
* `$(` where argument might be HTML / template strings
* `$.parseHTML(` especially with `keepScripts=true` ([jQuery API][2])
* `.load(` (and whether selector is appended; script behavior differs) ([jQuery API][3])
* Script execution / dynamic code:
* `$.getScript(`, `dataType: "script"` ([jQuery API][4])
* `dataType: "jsonp"` or `jsonp:` usage; `callback=?` patterns ([jQuery API][5])
* `eval`, `new Function`, `setTimeout("…")`, `$.globalEval`
* Dangerous attribute writes:
* `.attr("href", …)`, `.attr("src", …)`, `.attr("style", …)`
* Any assignment of `javascript:`-like schemes or suspicious URL construction ([MDN Web Docs][6])
* Selector construction:
* `$("#" + user)` and similar; fix via `$.escapeSelector` ([jQuery API][20])
* Prototype pollution:
* `$.extend(true, …, userObj)`; ensure jQuery >= 3.4.0 and filter dangerous keys ([NVD][13])
* CSRF posture for AJAX:
* `$.post(` / `$.ajax({ method: ... })` with cookies and no CSRF token/header ([OWASP Cheat Sheet Series][19])
* Defense-in-depth:
* Absence of CSP/security headers in configs (or not visible; require runtime verification) ([OWASP Cheat Sheet Series][12])
Always try to confirm:
* data origin (untrusted vs trusted)
* sink type (HTML insertion / script execution / attribute / selector / object merge)
* protective controls present (sanitizer, allowlists, CSP, Trusted Types, CSRF validation)
---
## 6) Sources (accessed 2026-01-27)
Primary jQuery project documentation and release notes:
* jQuery 4.0.0 release notes (Trusted Types/CSP changes; version info): `https://blog.jquery.com/2026/01/17/jquery-4-0-0/`. ([blog.jquery.com][7])
* Download jQuery (latest version info; CDN + SRI guidance): `https://jquery.com/download/`. ([jquery.com][8])
* jQuery API: `.html()`: `https://api.jquery.com/html/`. ([jQuery API][21])
* jQuery API: `.text()`: `https://api.jquery.com/text/`. ([jQuery API][14])
* jQuery API: `.append()`: `https://api.jquery.com/append/`. ([jQuery API][22])
* jQuery API: `.load()` (script execution behavior): `https://api.jquery.com/load/`. ([jQuery API][3])
* jQuery API: `jQuery.parseHTML(…, keepScripts)`: `https://api.jquery.com/jQuery.parseHTML/`. ([jQuery API][2])
* jQuery API: `$.ajax()` (`jsonp: false` security note): `https://api.jquery.com/jQuery.ajax/`. ([jQuery API][5])
* jQuery API: `$.getScript()` (executes script): `https://api.jquery.com/jQuery.getScript/`. ([jQuery API][4])
* jQuery API: `jQuery.escapeSelector()`: `https://api.jquery.com/jQuery.escapeSelector/`. ([jQuery API][20])
jQuery vulnerabilities / advisories:
* NVD CVE-2019-11358 (prototype pollution; jQuery < 3.4.0): `https://nvd.nist.gov/vuln/detail/CVE-2019-11358`. ([NVD][13])
* NVD CVE-2020-11022 (XSS risk in DOM manipulation methods; patched in 3.5.0): `https://nvd.nist.gov/vuln/detail/CVE-2020-11022`. ([NVD][1])
* NVD CVE-2020-11023 (XSS risk involving `<option>`; patched in 3.5.0): `https://nvd.nist.gov/vuln/detail/CVE-2020-11023`. ([NVD][23])
* GitHub Security Advisory GHSA-gxr4-xjj5-5px2 (jQuery htmlPrefilter XSS; patched in 3.5.0): `https://github.com/jquery/jquery/security/advisories/GHSA-gxr4-xjj5-5px2`. ([GitHub][16])
OWASP Cheat Sheet Series (web app security foundations relevant to jQuery usage):
* XSS Prevention: `https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html`. ([OWASP Cheat Sheet Series][24])
* DOM-based XSS Prevention: `https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html`. ([OWASP Cheat Sheet Series][25])
* CSRF Prevention: `https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html`. ([OWASP Cheat Sheet Series][19])
* HTTP Security Headers: `https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html`. ([OWASP Cheat Sheet Series][12])
* Content Security Policy Cheat Sheet: `https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html`. ([OWASP Cheat Sheet Series][9])
Browser/platform references (SRI, CSP, Trusted Types, and dangerous URL schemes):
* MDN: Subresource Integrity (SRI): `https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity`. ([MDN Web Docs][26])
* W3C: SRI specification: `https://www.w3.org/TR/sri-2/`. ([W3C][27])
* MDN: CSP guide: `https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP`. ([MDN Web Docs][28])
* MDN: `require-trusted-types-for` directive: `https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for`. ([MDN Web Docs][11])
* MDN: Trusted Types API: `https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API`. ([MDN Web Docs][29])
* W3C: Trusted Types specification: `https://www.w3.org/TR/trusted-types/`. ([W3C][10])
* MDN: `javascript:` URL scheme warning: `https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/javascript`. ([MDN Web Docs][6])
* DOMPurify project documentation: `https://github.com/cure53/DOMPurify`. ([GitHub][17])
[1]: https://nvd.nist.gov/vuln/detail/cve-2020-11022?utm_source=chatgpt.com "CVE-2020-11022 Detail - NVD"
[2]: https://api.jquery.com/jQuery.parseHTML/?utm_source=chatgpt.com "jQuery.parseHTML()"
[3]: https://api.jquery.com/load/?utm_source=chatgpt.com ".load() | jQuery API Documentation"
[4]: https://api.jquery.com/jQuery.getScript/?utm_source=chatgpt.com "jQuery.getScript()"
[5]: https://api.jquery.com/jQuery.ajax/?utm_source=chatgpt.com "jQuery.ajax()"
[6]: https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/javascript?utm_source=chatgpt.com "javascript: URLs - URIs - MDN Web Docs"
[7]: https://blog.jquery.com/2026/01/17/jquery-4-0-0/ "jQuery 4.0.0 | Official jQuery Blog"
[8]: https://jquery.com/download/ "Download jQuery | jQuery"
[9]: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html?utm_source=chatgpt.com "Content Security Policy - OWASP Cheat Sheet Series"
[10]: https://www.w3.org/TR/trusted-types/?utm_source=chatgpt.com "Trusted Types"
[11]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for?utm_source=chatgpt.com "Content-Security-Policy: require-trusted-types-for directive"
[12]: https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html?utm_source=chatgpt.com "HTTP Security Response Headers Cheat Sheet"
[13]: https://nvd.nist.gov/vuln/detail/cve-2019-11358?utm_source=chatgpt.com "CVE-2019-11358 Detail - NVD"
[14]: https://api.jquery.com/text/?utm_source=chatgpt.com ".text() | jQuery API Documentation"
[15]: https://api.jquery.com/val/?utm_source=chatgpt.com ".val() | jQuery API Documentation"
[16]: https://github.com/jquery/jquery/security/advisories/GHSA-gxr4-xjj5-5px2 "Potential XSS vulnerability in jQuery.htmlPrefilter and related methods · Advisory · jquery/jquery · GitHub"
[17]: https://github.com/cure53/DOMPurify?utm_source=chatgpt.com "DOMPurify - a DOM-only, super-fast, uber-tolerant XSS ..."
[18]: https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API?utm_source=chatgpt.com "HTML Sanitizer API - MDN Web Docs"
[19]: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html?utm_source=chatgpt.com "Cross-Site Request Forgery Prevention Cheat Sheet"
[20]: https://api.jquery.com/jQuery.escapeSelector/?utm_source=chatgpt.com "jQuery.escapeSelector()"
[21]: https://api.jquery.com/html/?utm_source=chatgpt.com ".html() | jQuery API Documentation"
[22]: https://api.jquery.com/append/?utm_source=chatgpt.com ".append() | jQuery API Documentation"
[23]: https://nvd.nist.gov/vuln/detail/cve-2020-11023?utm_source=chatgpt.com "CVE-2020-11023 Detail - NVD"
[24]: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html?utm_source=chatgpt.com "Cross Site Scripting Prevention - OWASP Cheat Sheet Series"
[25]: https://cheatsheetseries.owasp.org/cheatsheets/DOM_based_XSS_Prevention_Cheat_Sheet.html?utm_source=chatgpt.com "DOM based XSS Prevention Cheat Sheet"
[26]: https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity?utm_source=chatgpt.com "Subresource Integrity - Security - MDN Web Docs"
[27]: https://www.w3.org/TR/sri-2/?utm_source=chatgpt.com "Subresource Integrity"
[28]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP?utm_source=chatgpt.com "Content Security Policy (CSP) - HTTP - MDN Web Docs"
[29]: https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API?utm_source=chatgpt.com "Trusted Types API - MDN Web Docs"
.blackbox/skills/security-best-practices/references/javascript-typescript-nextjs-web-server-security.md
+1144
View File
File diff suppressed because it is too large Load Diff
.blackbox/skills/security-best-practices/references/javascript-typescript-react-web-frontend-security.md
+990
View File
@@ -0,0 +1,990 @@
# React (JavaScript/TypeScript) Web Security Spec (React 19.x, TypeScript 5.x)
This document is designed as a **security spec** that supports:
1. **Secure-by-default code generation** for new React code.
2. **Security review / vulnerability hunting** in existing React code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
---
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
* MUST NOT request, output, log, or commit secrets (API keys, OAuth client secrets, private keys, session cookies, JWTs, signing keys).
* Frontend note: anything shipped to the browser is observable by end users and attackers (view-source, devtools, proxies); never treat client code or “env vars in the bundle” as secret. ([create-react-app.dev][1])
* MUST NOT “fix” security by disabling protections (e.g., turning off CSP to “make it work”, adding `unsafe-inline`/`unsafe-eval` without a documented, constrained plan, disabling CSRF protections when using cookies, widening CORS, skipping sanitization, or “temporary” bypasses that ship). ([OWASP Cheat Sheet Series][2])
* MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and configuration values that justify the claim.
* MUST treat uncertainty honestly: if a protection might exist in infra (CDN/WAF/reverse proxy), report it as “not visible in app code; verify via runtime headers / edge config”.
* MUST assume any data that crosses a trust boundary (URL, storage, network, postMessage, third-party scripts) can be attacker-influenced unless proven otherwise (see §2.1).
---
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new React code or modify existing code:
* MUST follow every **MUST** requirement in this spec.
* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
* MUST prefer safe-by-default APIs and proven libraries over custom security code.
* MUST avoid introducing new risky sinks (raw HTML insertion, direct DOM sinks like `innerHTML`, dynamic code execution, untrusted redirects/navigation, third‑party script injection, unsafe token storage, etc.). ([MDN Web Docs][3])
### 1.2 Passive review mode (always on while editing)
While working anywhere in a React repo (even if the user did not ask for a security scan):
* MUST “notice” violations of this spec in touched/nearby code.
* SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
* MUST systematically search the codebase for violations of this spec.
* MUST output findings in a structured format (see §2.3).
Recommended audit order:
1. App entrypoints, build tooling (Vite/Webpack/CRA/Next), deployment configs, CDN/static hosting config.
2. Secrets & configuration exposure (env vars, runtime config injection, source maps).
3. Rendering of untrusted data (XSS/DOM XSS), especially `dangerouslySetInnerHTML`, markdown/HTML renderers, URL attributes.
4. Direct DOM usage and dangerous JS execution (`innerHTML`, `eval`, `new Function`, `document.write`, etc.).
5. Auth & session patterns (token storage, cookies, CSRF interactions, OAuth flows).
6. Network layer (axios/fetch wrappers, dynamic base URLs, credentialed requests, data exfil risks).
7. Navigation & redirect handling (open redirects, `window.location`, `target=_blank`, `window.open`).
8. Third-party scripts/tags/analytics and integrity controls (CSP, SRI).
9. Service worker/PWA behavior (HTTPS, caching rules, update strategy).
10. Security headers posture (CSP, clickjacking, nosniff, referrer policy) in app or at the edge. ([OWASP Cheat Sheet Series][2])
---
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
* URL-derived data: `window.location`, query params, hash fragments, route params.
* Any data from browser storage: `localStorage`, `sessionStorage`, `IndexedDB` (including data previously written by the app—because XSS or extensions can tamper with it). ([OWASP Cheat Sheet Series][4])
* Any data from cross-window messaging: `window.postMessage` payloads. ([OWASP Cheat Sheet Series][4])
* Any data from remote APIs, webhooks proxied to the client, GraphQL responses, CMS content, feature flag services.
* Any persisted user content (profiles, comments, rich text, markdown) rendered in the UI.
* Any data produced by third-party scripts or tag managers (treat as untrusted unless strongly controlled). ([OWASP Cheat Sheet Series][5])
### 2.2 State-changing request (frontend perspective)
A request is state-changing if it can create/update/delete data, change auth/session state, trigger side effects (purchase, email send, webhook), or initiate privileged actions.
Frontend-specific note:
* State changes are often triggered by `fetch/axios` calls or form submissions. If authentication is cookie-based, these calls can be CSRF-relevant (§4 REACT-CSRF-001). ([OWASP Cheat Sheet Series][6])
### 2.3 Required audit finding format
For each issue found, output:
* Rule ID:
* Severity: Critical / High / Medium / Low
* Location: file path + component/function + line(s)
* Evidence: the exact code/config snippet
* Impact: what could go wrong, who can exploit it
* Fix: safe change (prefer minimal diff)
* Mitigation: defense-in-depth if immediate fix is hard
* False positive notes: what to verify if uncertain
---
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common React frontend misconfigurations.
### 3.1 Production build and configuration hygiene (MUST)
* MUST ship a production build (minified, no dev-only overlays/tools, correct mode flags).
* MUST ensure build-time configuration does not embed secrets into the shipped JS/HTML/CSS. Build-time “environment variables” are not secret; treat them as public. ([create-react-app.dev][1])
* SHOULD treat source maps as sensitive operational artifacts:
* Either don’t publish them publicly, or publish them only where intended (e.g., behind auth or to an error-reporting provider), because they can reveal code structure and internal URLs.
### 3.2 Browser-enforced protections (SHOULD, but baseline expectation for modern apps)
* SHOULD deploy a CSP as defense-in-depth against XSS, and keep it compatible with your React build (avoid `unsafe-inline` and `unsafe-eval` unless strictly necessary and documented). ([OWASP Cheat Sheet Series][2])
* SHOULD use Subresource Integrity (SRI) for any third-party script/style loaded from a CDN (or self-host instead). ([MDN Web Docs][7])
* SHOULD enable clickjacking defenses via `frame-ancestors` (CSP) and/or `X-Frame-Options`, unless embedding is an explicit product requirement. ([MDN Web Docs][8])
### 3.3 High-risk features baseline (MUST if used)
* If rendering any user-provided HTML/markdown/rich text:
* MUST sanitize before insertion and avoid raw DOM sinks. ([OWASP Cheat Sheet Series][9])
* If using service workers / PWA:
* MUST serve over HTTPS and implement a safe caching/update strategy (service workers are powerful request/response proxies). ([MDN Web Docs][10])
---
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### REACT-CONFIG-001: Never embed secrets in the client bundle (env vars are public)
Severity: Critical (if secrets exposed)
Required:
* MUST NOT place secrets in React code, in `public/` assets, or in build-time environment variables intended for client consumption.
* MUST assume any value available to the React app at runtime can be extracted by an attacker.
Insecure patterns:
* Using build-time env vars for secrets:
* `process.env.REACT_APP_*` containing private keys or credentials.
* `import.meta.env.VITE_*` containing secrets.
* Hard-coded secrets in JS/TS, `.env` committed, or secrets in `public/config.json` served to all users.
Detection hints:
* Search for:
* `REACT_APP_`, `VITE_`, `NEXT_PUBLIC_`, `process.env.`, `import.meta.env.`
* `apiKey`, `secret`, `token`, `private`, `password`, `client_secret`
* Inspect `public/` for runtime config JSON.
Fix:
* Move secrets server-side (API, BFF, serverless function).
* Use a backend to mint short-lived, scoped tokens if the browser needs to call third-party APIs.
Notes:
* CRA explicitly warns not to store secrets and notes env vars are embedded into the build and visible to anyone inspecting files. ([create-react-app.dev][1])
* Vite explicitly notes that variables exposed to client code end up in the client bundle and should not contain sensitive info. ([vitejs][11])
---
### REACT-XSS-001: Do not use `dangerouslySetInnerHTML` with untrusted content (sanitize or avoid)
Severity: High (Only if you can prove attacker-controlled HTML reaches it)
Required:
* MUST avoid `dangerouslySetInnerHTML` unless absolutely necessary.
* If it must be used:
* MUST sanitize untrusted HTML with a proven sanitizer (e.g., DOMPurify) and an allowlist-oriented configuration.
* MUST keep the sanitization logic centralized and heavily reviewed.
* SHOULD add a CSP and consider Trusted Types (see REACT-TT-001).
Insecure patterns:
* `<div dangerouslySetInnerHTML={{ __html: userHtml }} />` where `userHtml` is from API/URL/storage.
* “Sanitization” done with regexes, ad-hoc stripping, or incomplete allowlists.
Detection hints:
* Grep: `dangerouslySetInnerHTML`, `__html:`
* Trace the origin of the HTML string (API/CMS/URL/localStorage).
Fix:
* Replace with safe rendering:
* Render structured data as React elements/components instead of HTML strings.
* If rich text is required, sanitize with DOMPurify (or equivalent) and render the sanitized output.
* Add CSP; remove dangerous sinks where possible.
Notes:
* React explicitly warns that `dangerouslySetInnerHTML` is dangerous and can introduce XSS if misused. ([React][12])
* OWASP explicitly calls out React’s `dangerouslySetInnerHTML` without sanitization as a common framework “escape hatch” pitfall. ([OWASP Cheat Sheet Series][9])
* DOMPurify describes itself as an XSS sanitizer for HTML/SVG/MathML. ([GitHub][13])
---
### REACT-XSS-002: Rely on React’s escaping-by-default behavior; do not bypass it
Severity: High (when bypassed)
Required:
* MUST render untrusted strings via normal JSX interpolation (`{value}`) and React props, which are escaped by default.
* MUST NOT build HTML strings from untrusted data and then inject them into the DOM via any means.
* SHOULD treat any “escape hatch” as high risk and require review.
Insecure patterns:
* Converting untrusted text into HTML and injecting it:
* `element.innerHTML = userValue`
* `document.write(userValue)`
* `insertAdjacentHTML(..., userValue)`
Detection hints:
* Grep for DOM sinks: `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`, `DOMParser`, `createContextualFragment`.
Fix:
* Render text content through React (JSX) so it is escaped.
* If you truly need HTML, sanitize and apply REACT-XSS-001 + REACT-TT-001.
Notes:
* React documentation (JSX) states that React DOM escapes values embedded in JSX before rendering to help prevent injection attacks. ([React][14])
---
### REACT-DOM-001: Avoid DOM XSS injection sinks in React code (use safe alternatives)
Severity: High
Required:
* MUST avoid direct DOM injection sinks, even outside React rendering, unless strongly controlled.
* If a DOM sink is required:
* MUST ensure inputs are trusted/validated/sanitized.
* SHOULD enforce Trusted Types (REACT-TT-001).
Insecure patterns:
* `someEl.innerHTML = untrusted`
* `document.write(untrusted)`
* `new DOMParser().parseFromString(untrusted, 'text/html')` followed by insertion
Detection hints:
* Grep for: `innerHTML`, `outerHTML`, `document.write`, `DOMParser`, `Range().createContextualFragment`, `insertAdjacentHTML`
Fix:
* Prefer:
* `textContent` for text insertion.
* React rendering rather than manual DOM manipulation.
* A vetted sanitizer for any required HTML parsing.
Notes:
* Trusted Types documentation defines HTML sinks like `Element.innerHTML` and `document.write()` as injection sinks that can execute script when given attacker-controlled input. ([MDN Web Docs][3])
* OWASP HTML5 guidance recommends using `textContent` instead of `innerHTML` for assigning untrusted data. ([OWASP Cheat Sheet Series][4])
---
### REACT-URL-001: Validate and constrain untrusted URLs used in `href`, `src`, navigation, and redirects
Severity: High Only when you can prove they are attacker controlled
Required:
* MUST treat any URL derived from untrusted input as dangerous.
* MUST allowlist schemes and (when applicable) hosts:
* Typically allow only `https:` (and maybe `http:` for localhost/dev) and relative URLs for in-app navigation.
* MUST explicitly block `javascript:` and dangerous `data:` uses unless you have specialized validation and a clear use case.
* SHOULD prefer same-site relative paths (e.g., `/settings`) over absolute URLs.
* MUST validate “returnTo/next/redirect” parameters (see REACT-REDIRECT-001).
Insecure patterns:
* `<img src={userProvidedUrl}>...` (can be used for tracking / data exfil; also risky if used for scripts/iframes)
* `window.location = next`
* `navigate(next)` where `next` comes from query params without validation
Detection hints:
* Search for:
* `href={`, `src={`, `window.location`, `location.href`, `window.open`, `navigate(`, `redirectTo`, `returnTo`, `next=`
* Track whether the value is derived from URL/query/storage/API.
Fix:
* Implement a shared `safeUrl()` utility:
* Parse with `new URL(value, base)`
* Enforce scheme allowlist and host allowlist (or enforce same-origin)
* For redirects: allow only relative paths (starting with `/`) or a strict allowlist of absolute origins.
* Fall back to a safe default when validation fails.
Notes:
* OWASP explicitly notes React’s `dangerouslySetInnerHTML` risk and also states React cannot safely handle `javascript:` or `data:` URLs without specialized validation. ([OWASP Cheat Sheet Series][9])
---
### REACT-MARKUP-001: Markdown / rich text rendering must be configured safely
Severity: Medium
Required:
* MUST assume markdown/rich text can be attacker-controlled if it comes from users or CMS.
* MUST ensure raw HTML is not rendered unless sanitized.
* SHOULD prefer markdown renderers that:
* Do not allow raw HTML by default, or
* Can be configured to disallow raw HTML, or
* Sanitize HTML output before rendering.
Insecure patterns:
* Markdown rendering with “raw HTML passthrough” enabled (e.g., options/plugins that allow HTML).
* Rendering user-provided SVG/MathML/HTML inline without sanitization.
Detection hints:
* Search for common libraries and risky options:
* `marked`, `markdown-it`, `react-markdown`, `rehype-raw`, `sanitize: false`, `allowDangerousHtml`, etc.
* Look for `dangerouslySetInnerHTML` used with “markdown output”.
Fix:
* Disable raw HTML passthrough.
* Sanitize output with a proven sanitizer (e.g., DOMPurify) before rendering.
Notes:
* OWASP XSS guidance emphasizes that framework escape hatches require output encoding and/or HTML sanitization. ([OWASP Cheat Sheet Series][9])
---
### REACT-TT-001: Use Trusted Types (with CSP) to harden DOM XSS sinks where feasible
Severity: Low
Required:
* SHOULD consider enabling Trusted Types in report-only mode first, then enforce once violations are addressed.
* SHOULD centralize Trusted Types policies and treat them as high-risk code requiring review.
* MUST NOT create permissive policies that simply “pass through” untrusted strings.
Insecure patterns:
* A Trusted Types policy that returns the raw string without sanitization for HTML sinks.
* Many scattered policies across the codebase (hard to audit).
Detection hints:
* Search for:
* `trustedTypes.createPolicy`
* CSP directives: `require-trusted-types-for`, `trusted-types`
* Search for remaining DOM sinks (REACT-DOM-001).
Fix:
* Implement a small number of tightly scoped policies:
* HTML policy uses sanitizer (DOMPurify or equivalent).
* Script URL policy uses strict allowlists.
* Run in report-only mode, fix violations, then enforce.
Notes:
* MDN describes Trusted Types as a way to ensure input is transformed (commonly sanitized) before being passed to injection sinks, and highlights HTML sinks (`innerHTML`, `document.write`) and JS URL sinks (`script.src`). ([MDN Web Docs][3])
* The W3C Trusted Types spec frames this as reducing DOM XSS risk by locking down sinks to typed values created by reviewed policies. ([W3C][15])
---
### REACT-CSP-001: Deploy and maintain a CSP as defense-in-depth (especially when rendering untrusted content)
Severity: Medium to High
Required:
* SHOULD deploy CSP in production; MUST do so for apps that render untrusted content or integrate third-party scripts.
* SHOULD avoid `unsafe-inline` and `unsafe-eval` when possible.
* SHOULD use CSP nonces/hashes for inline scripts if needed, and keep policy realistic.
* SHOULD use CSP to require/encourage SRI where appropriate.
Insecure patterns:
* No CSP at all on the app shell (SPA entry HTML).
* CSP that relies on `unsafe-inline`/`unsafe-eval` broadly without justification.
* `script-src *` or overly broad sources.
Detection hints:
* Look for CSP configuration:
* Server/CDN config, headers in `index.html` responses, or framework config.
* If absent in repo, mark as “verify at edge”.
Fix:
* Add CSP via HTTP response headers (preferred).
* Start with report-only to reduce breakage, then enforce.
Notes:
* OWASP describes CSP as “defense in depth” against XSS and notes it can help enforce SRI even on static sites, but should not be the only defense. ([OWASP Cheat Sheet Series][2])
---
### REACT-SRI-001: Use Subresource Integrity (SRI) for third-party scripts and styles (or self-host)
Severity: Low
Required:
* MUST treat third-party JS as equivalent to running arbitrary code in your origin.
* If loading from a CDN or third party:
* SHOULD use SRI (`integrity=...`) and `crossorigin` where applicable.
* SHOULD pin exact versions (avoid “latest” URLs).
* SHOULD prefer self-hosting for critical code.
Insecure patterns:
* `<script src="https://cdn.example.com/lib/latest.js"></script>` with no integrity.
* Tag managers that dynamically load arbitrary scripts without governance.
Detection hints:
* Search in `public/index.html`, templates, or SSR wrappers for:
* `<script src=`, `<link rel="stylesheet" href=`
* Tag manager snippets (GTM, Segment, etc.)
* Identify scripts loaded dynamically in runtime JS.
Fix:
* Add SRI hashes for stable third-party assets or self-host.
* Apply governance controls for tag managers (see REACT-3P-001).
Notes:
* MDN describes SRI as a security feature enabling browsers to verify fetched resources (e.g., from a CDN) haven’t been manipulated by checking a cryptographic hash. ([MDN Web Docs][7])
* OWASP CSP guidance notes CSP can enforce SRI and is useful even on static sites. ([OWASP Cheat Sheet Series][2])
---
### REACT-3P-001: Third-party JavaScript and tag managers must be minimized and governed
Severity: High
Required:
* MUST minimize third-party scripts and treat each as a supply-chain risk.
* MUST know exactly what third-party JS executes in your origin and why.
* SHOULD implement governance:
* Review and pin versions (or mirror in-house).
* Restrict data access (data-layer approach).
* Use SRI and CSP; consider sandboxing untrusted UI in iframes where possible.
Insecure patterns:
* Unreviewed analytics/ads scripts running with full access to DOM, cookies, storage, and user data.
* Tag managers that can be changed by non-engineering roles with no change control.
Detection hints:
* Search for common vendor snippets in HTML/JS:
* GTM, Segment, Hotjar, FullStory, etc.
* Look for dynamic script insertion:
* `document.createElement('script')`, `.src = ...`, `.appendChild(script)`
Fix:
* Reduce to only necessary vendors.
* Where feasible:
* Self-host or mirror scripts.
* Use SRI.
* Limit data exposure via a controlled data layer.
Notes:
* OWASP notes third-party JS server compromise can inject malicious JS, and highlights risks like arbitrary code execution and disclosure of sensitive info to third parties. ([OWASP Cheat Sheet Series][5])
---
### REACT-AUTH-001: Token and session handling must be resilient to XSS (avoid sensitive storage in Web Storage)
Severity: Medium
Required:
* SHOULD avoid storing session identifiers or long-lived tokens in `localStorage` (and generally in Web Storage) because XSS can exfiltrate them.
* If tokens must exist client-side:
* SHOULD prefer in-memory storage with short lifetimes and refresh mechanisms.
* MUST scope and rotate tokens; avoid long-lived bearer tokens in persistent storage.
* SHOULD prefer HTTPOnly cookies for session tokens when possible (requires CSRF strategy: see REACT-CSRF-001).
Insecure patterns:
* `localStorage.setItem('token', ...)` / `sessionStorage.setItem('token', ...)` for auth tokens.
* Persisting refresh tokens in `localStorage`.
* Treating data from Web Storage as trusted.
Detection hints:
* Grep for: `localStorage.`, `sessionStorage.`, `setItem(`, `getItem(`, `token`, `jwt`, `refresh`
* Search auth code for “remember me” storing tokens persistently.
Fix:
* Move to HTTPOnly cookies (server change) + CSRF protections, or use short-lived in-memory tokens.
* Reduce token scope and lifetime.
Notes:
* OWASP HTML5 guidance recommends avoiding sensitive info and session identifiers in local storage and warns that a single XSS can steal all data in Web Storage. ([OWASP Cheat Sheet Series][4])
* OAuth browser-based apps guidance discusses that tokens stored in persistent browser storage like localStorage can be accessible to malicious JS (e.g., via XSS). ([IETF Datatracker][16])
---
### REACT-CSRF-001: Cookie-authenticated, state-changing requests MUST be CSRF-protected
Severity: High
NOTE: If the application does not use cookie based auth (using Authentication header for example), then CSRF is not a concern.
Required:
* If the app relies on cookies for authentication:
* MUST protect state-changing requests (POST/PUT/PATCH/DELETE) against CSRF.
* SHOULD include a CSRF token mechanism (synchronizer token or double-submit cookie) or other robust pattern appropriate to the backend.
* SHOULD use SameSite cookies as defense-in-depth, not as the sole defense.
Insecure patterns:
* `fetch('/api/transfer', { method: 'POST', credentials: 'include' })` with no CSRF token/header, relying only on cookies.
* Using GET for state-changing operations.
Detection hints:
* Enumerate state-changing network calls and check:
* Is `credentials: 'include'` or `withCredentials: true` used?
* Is a CSRF token header included (e.g., `X-CSRF-Token`)?
* Search for “csrf” utilities; if absent, treat as suspicious.
Fix:
* Add CSRF token flow:
* Fetch token from a safe endpoint and attach to state-changing requests.
* Validate server-side.
* Keep SameSite cookies and Origin/Referer validation as defense-in-depth.
Notes:
* OWASP CSRF guidance explains SameSite behavior (Lax/Strict/None) as a defense-in-depth technique and why Lax is often the usability/security balance, but it is not a complete substitute for CSRF protections. ([OWASP Cheat Sheet Series][6])
---
### REACT-AUTHZ-001: Do not rely on frontend-only authorization
Severity: High (only if used as primary protection)
Required:
* MUST treat all frontend authorization checks as UX only.
* MUST enforce authorization on the server for any protected resource or action.
Insecure patterns:
* “Protected” actions hidden in UI but callable by API without server checks.
* Client checks like `if (user.isAdmin) { showAdminPanel(); }` with no server-side enforcement.
Detection hints:
* Look for UI gating around sensitive actions and verify server endpoints enforce authorization.
* In a frontend-only audit, report as “client checks are not security; verify backend”.
Fix:
* Add/confirm server-side authorization checks.
* Keep frontend gating only as convenience.
Notes:
* This is a general web app security property; React cannot protect server resources by itself.
---
### REACT-NET-001: Prevent data exfiltration and credential leakage via dynamic outbound requests
Severity: Medium to High
Required:
* MUST avoid making authenticated requests to attacker-controlled origins.
* SHOULD avoid allowing user input to control request destination (scheme/host/port).
* SHOULD centralize network clients (fetch/axios) with:
* fixed `baseURL` (or strict allowlist),
* strict handling of redirects,
* explicit `credentials` usage.
Insecure patterns:
* `fetch(userProvidedUrl, { credentials: 'include' })`
* `axios.create({ baseURL: userProvidedBase })`
* “URL fetch/preview” features in the client that hit arbitrary domains with sensitive headers.
Detection hints:
* Search for `fetch(` / `axios(` where the first argument or `baseURL` is derived from:
* query params, localStorage, API responses, postMessage
* Search for `credentials: 'include'`, `withCredentials: true`.
Fix:
* Enforce destination allowlists; disallow cross-origin requests unless explicitly required.
* Strip credentials/Authorization headers for any non-allowlisted destination.
Notes:
* Even if the browser limits some cross-origin behavior, leaking tokens/headers to untrusted endpoints is still a common failure mode.
---
### REACT-REDIRECT-001: Prevent open redirects and untrusted navigation
Severity: Medium
Required:
* MUST validate redirect/navigation targets derived from untrusted input (`next`, `returnTo`, `redirect`).
* SHOULD only allow same-site relative paths, or a strict allowlist of trusted origins for absolute URLs.
Insecure patterns:
* `window.location.href = new URLSearchParams(location.search).get('next')`
* `navigate(next)` where `next` comes from query params.
Detection hints:
* Search for: `next`, `returnTo`, `redirect`, `window.location`, `navigate(`
* Trace origin of the redirect target.
Fix:
* Only allow relative paths (`/^\/[^\s]*$/`) or allowlisted origins.
* Fall back to a safe default (e.g., `/`) when invalid.
Notes:
* Open redirects are frequently used in phishing and can undermine SSO/OAuth flows.
---
### REACT-SW-001: Service workers are high-privilege; require HTTPS and safe caching/update rules
Severity: Medium
Required:
* MUST serve service workers over HTTPS (except `localhost` dev), and deploy only in secure contexts.
* MUST avoid caching sensitive authenticated API responses unless explicitly designed and threat-modeled.
* SHOULD implement safe update strategy (prompt reload, versioned caches, remove old caches on activate).
Insecure patterns:
* Registering a service worker for an authenticated app and caching “everything” indiscriminately.
* Long-lived caches containing PII or user-specific content shared across accounts.
Detection hints:
* Search for:
* `navigator.serviceWorker.register`
* `workbox`, `precacheAndRoute`, custom `fetch` handlers
* Inspect caching patterns (`caches.open`, `cache.put`, `respondWith`).
Fix:
* Restrict caching to static assets only (JS/CSS/images) unless you have a designed offline model.
* Ensure cache keys are user-scoped if user-specific data must be cached.
* Provide a clear update mechanism.
Notes:
* MDN notes service workers require HTTPS for security reasons and act like a proxy for requests/responses. ([MDN Web Docs][10])
* “Secure contexts” exist to prevent MITM attackers from accessing powerful APIs; service workers are an example of such a powerful feature. ([MDN Web Docs][18])
---
### REACT-HEADERS-001: Ensure essential security headers are set for the React app shell (app or edge)
Severity: Medium
Required (typical SPA served from an origin):
* SHOULD set:
* CSP (`Content-Security-Policy`)
* `X-Content-Type-Options: nosniff`
* Clickjacking protection (`frame-ancestors` in CSP and/or `X-Frame-Options`)
* `Referrer-Policy`
* `Permissions-Policy` as appropriate
* MUST ensure these are set somewhere (CDN/edge/server), even if not in repo.
Insecure patterns:
* No security headers anywhere (app or edge).
* CSP missing on apps that render untrusted content or use third-party scripts.
Detection hints:
* Check server/CDN config in repo (nginx, Cloudflare, Vercel config, etc.).
* If absent, flag as “verify at runtime/edge”.
Fix:
* Set headers centrally at the edge.
* Keep CSP realistic and iterative (report-only → enforce).
Notes:
* MDN clickjacking guidance discusses defenses including `X-Frame-Options` and CSP `frame-ancestors`. ([MDN Web Docs][8])
* OWASP CSP guidance explains delivery via response headers and recommends headers as the preferred mechanism. ([OWASP Cheat Sheet Series][2])
---
### REACT-POSTMSG-001: `postMessage` must validate origin and treat payload as untrusted data
Severity: Medium to High (depends on what messages can do)
Required:
* MUST specify exact `targetOrigin` when sending messages (not `*`) unless there is a strict reason.
* MUST validate `event.origin` on receipt and validate message shape.
* MUST NOT evaluate message data as code or insert it into the DOM as HTML.
Insecure patterns:
* `window.postMessage(data, '*')` to unknown targets.
* Receiving:
* `window.addEventListener('message', (e) => { eval(e.data) })`
* `element.innerHTML = e.data`
Detection hints:
* Search: `postMessage(`, `addEventListener('message'`
* Check for origin checks and safe handling.
Fix:
* Add strict origin allowlists and schema validation (e.g., zod).
* Treat message payload strictly as data; render safely via React.
Notes:
* OWASP HTML5 guidance recommends specifying expected origin for `postMessage`, checking sender origin, validating data, and avoiding eval/innerHTML with message content. ([OWASP Cheat Sheet Series][4])
---
### REACT-FILE-001: File uploads and previews must not create client-side active content vulnerabilities
Severity: Medium (can be High if stored-XSS possible)
Required:
* MUST treat user-uploaded files and previews as potentially malicious.
* MUST NOT render uploaded HTML/SVG/other active content inline unless sanitized and explicitly required.
* SHOULD validate file types client-side for UX, but MUST rely on server-side validation for security.
Insecure patterns:
* Rendering user-uploaded HTML as content.
* Inline rendering of untrusted SVG/HTML via `dangerouslySetInnerHTML` or `<iframe srcdoc=...>` without sanitization.
Detection hints:
* Search for upload components and preview logic:
* `input type="file"`, `FileReader`, `URL.createObjectURL`, `<iframe>`, `<object>`, `<embed>`.
* Trace where uploaded content is later displayed.
Fix:
* Restrict accepted types, sanitize where needed, and prefer download/attachment flows for risky types.
* Ensure server enforces the real policy (type checking, renaming, scanning, storing outside webroot).
Notes:
* OWASP file upload guidance highlights allowlisting extensions, validating file type, generating filenames, limiting size, storing outside webroot, and considering “client-side active content (XSS, CSRF, etc.)” when files are publicly retrievable. ([OWASP Cheat Sheet Series][19])
---
### REACT-SUPPLY-001: Dependency and supply-chain hygiene (frontend + build tooling)
Severity: Low
Required:
* MUST use a lockfile and enforce reproducible installs in CI.
* SHOULD regularly audit dependencies and respond quickly to advisories for:
* React, react-dom, router libs, build tooling (Vite/Webpack), sanitizers, auth libs, etc.
* SHOULD reduce exposure to install-time script attacks and typosquatting risk.
Audit focus:
* CI should use `npm ci` (or Yarn frozen lockfile / pnpm equivalent) to prevent drift.
* Use vulnerability scanning (`npm audit`, GitHub Dependabot/alerts, etc.).
Insecure patterns:
* No lockfile or lockfile ignored in CI.
* `npm install` in CI producing non-reproducible builds.
* Unpinned or unreviewed high-risk deps; sudden major updates without review.
* Blindly running install scripts from third-party packages.
Detection hints:
* Check for lockfiles: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`.
* Check CI scripts for `npm install` vs `npm ci`.
* Search for `postinstall` scripts and suspicious build steps.
Fix:
* Use lockfile and enforce it in CI (e.g., `npm ci`).
* Run audits regularly; pin/upgrade responsibly.
* Consider restricting install scripts where feasible.
Notes:
* npm docs describe `npm audit` as submitting the project dependency tree to the registry to receive a report of known vulnerabilities and (optionally) applying remediations via `npm audit fix`, while noting some vulns require manual review. ([npm Docs][20])
* npm docs describe `npm ci` as intended for automated/CI environments, requiring an existing lockfile and failing if `package.json` and lockfile do not match. ([npm Docs][21])
* OWASP NPM security guidance recommends enforcing the lockfile and explicitly calls out `npm ci` / `yarn install --frozen-lockfile` to abort on inconsistencies, and highlights the risk of install-time scripts and the option to use `--ignore-scripts` to reduce attack surface. ([OWASP Cheat Sheet Series][22])
---
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
* Raw HTML / XSS escape hatches:
* `dangerouslySetInnerHTML`, `__html:`
* Markdown HTML passthrough flags: `rehype-raw`, `allowDangerousHtml`, `sanitize: false`
* DOM XSS sinks:
* `innerHTML`, `outerHTML`, `insertAdjacentHTML`, `document.write`, `DOMParser`, `createContextualFragment`
* Dangerous JS execution:
* `eval(`, `new Function(`, `setTimeout("`, `setInterval("`
* Untrusted URL injection / navigation:
* `href={` / `src={` with untrusted values
* `window.location`, `location.href`, `window.open`, `navigate(`
* Query params: `next`, `returnTo`, `redirect`
* Token/session risk:
* `localStorage.setItem`, `sessionStorage.setItem`, `getItem(` with `token`, `jwt`, `refresh`
* Cookie/CSRF coupling:
* `credentials: 'include'`, `withCredentials: true` on state-changing requests without CSRF headers
* Third-party scripts:
* `<script src=...>` in `public/index.html`
* Tag manager snippets and dynamic script insertion
* Service workers:
* `navigator.serviceWorker.register`, Workbox usage, custom `fetch` handlers
* postMessage:
* `postMessage(` with `*`, missing `event.origin` checks
* Supply chain:
* Missing lockfile, CI uses `npm install`, no audit step, risky postinstall scripts
Always try to confirm:
* data origin (untrusted vs trusted)
* sink type (React escape hatch vs DOM sink vs navigation vs storage)
* protective controls present (sanitization, allowlists, CSP/Trusted Types, CSRF tokens, headers, governance)
---
## 6) Sources (accessed 2026-01-26)
Primary React documentation:
* React 19 stable announcement — `https://react.dev/blog/2024/12/05/react-19` ([React][23])
* React DOM docs: `dangerouslySetInnerHTML` warning — `https://react.dev/reference/react-dom/components/common#dangerouslysetting-the-inner-html` ([React][12])
* React (legacy) JSX escaping statement — `https://legacy.reactjs.org/docs/introducing-jsx.html` ([React][14])
OWASP Cheat Sheet Series:
* Cross Site Scripting Prevention (framework escape hatches; React `dangerouslySetInnerHTML`; URL validation notes) — `https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][9])
* Content Security Policy — `https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][2])
* Cross-Site Request Forgery Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][6])
* HTML5 Security (Web Storage, postMessage, tabnabbing, sandboxed frames) — `https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][4])
* Third Party JavaScript Management — `https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][5])
* File Upload — `https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][19])
* NPM Security best practices — `https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][22])
Browser / platform references (MDN, W3C):
* Trusted Types API — `https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API` ([MDN Web Docs][3])
* W3C Trusted Types spec — `https://www.w3.org/TR/trusted-types/` ([W3C][15])
* Subresource Integrity — `https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity` ([MDN Web Docs][7])
* Clickjacking defenses overview — `https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/Clickjacking` ([MDN Web Docs][8])
* Using Service Workers (HTTPS requirement; proxy-like behavior) — `https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers` ([MDN Web Docs][10])
* Secure contexts (powerful APIs restricted to HTTPS) — `https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts` ([MDN Web Docs][18])
* Link `rel` values (noopener/noreferrer) — `https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel` ([MDN Web Docs][17])
Build tooling / env exposure references:
* Create React App env variables warning — `https://create-react-app.dev/docs/adding-custom-environment-variables/` ([create-react-app.dev][1])
* Vite env variables security notes — `https://vite.dev/guide/env-and-mode` ([vitejs][11])
Auth/token storage guidance:
* OAuth 2.0 for Browser-Based Apps (token storage discussion) — `https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps` ([IETF Datatracker][16])
Dependency tooling references:
* npm audit docs — `https://docs.npmjs.com/cli/v10/commands/npm-audit/` ([npm Docs][20])
* npm ci docs — `https://docs.npmjs.com/cli/v10/commands/npm-ci/` ([npm Docs][21])
Sanitizer reference:
* DOMPurify — `https://github.com/cure53/DOMPurify` ([GitHub][13])
[1]: https://create-react-app.dev/docs/adding-custom-environment-variables/ "Adding Custom Environment Variables | Create React App"
[2]: https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html "Content Security Policy - OWASP Cheat Sheet Series"
[3]: https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API "Trusted Types API - Web APIs | MDN"
[4]: https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html "HTML5 Security - OWASP Cheat Sheet Series"
[5]: https://cheatsheetseries.owasp.org/cheatsheets/Third_Party_Javascript_Management_Cheat_Sheet.html "Third Party Javascript Management - OWASP Cheat Sheet Series"
[6]: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html "Cross-Site Request Forgery Prevention - OWASP Cheat Sheet Series"
[7]: https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity "Subresource Integrity - Security | MDN"
[8]: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/Clickjacking "Clickjacking - Security | MDN"
[9]: https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html "Cross Site Scripting Prevention - OWASP Cheat Sheet Series"
[10]: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers "Using Service Workers - Web APIs | MDN"
[11]: https://vite.dev/guide/env-and-mode "Env Variables and Modes | Vite"
[12]: https://react.dev/reference/react-dom/components/common "Common components (e.g. <div>) – React"
[13]: https://github.com/cure53/DOMPurify "GitHub - cure53/DOMPurify: DOMPurify - a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. DOMPurify works with a secure default, but offers a lot of configurability and hooks. Demo:"
[14]: https://legacy.reactjs.org/docs/introducing-jsx.html "Introducing JSX – React"
[15]: https://www.w3.org/TR/trusted-types/ "Trusted Types"
[16]: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps "
draft-ietf-oauth-browser-based-apps-26
"
[17]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel "HTML attribute: rel - HTML | MDN"
[18]: https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts "Secure contexts - Security | MDN"
[19]: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html "File Upload - OWASP Cheat Sheet Series"
[20]: https://docs.npmjs.com/cli/v10/commands/npm-audit "npm-audit | npm Docs"
[21]: https://docs.npmjs.com/cli/v10/commands/npm-ci "npm-ci | npm Docs"
[22]: https://cheatsheetseries.owasp.org/cheatsheets/NPM_Security_Cheat_Sheet.html "NPM Security - OWASP Cheat Sheet Series"
[23]: https://react.dev/blog/2024/12/05/react-19 "React v19 – React"
.blackbox/skills/security-best-practices/references/javascript-typescript-vue-web-frontend-security.md
+791
View File
@@ -0,0 +1,791 @@
# Vue.js Web Security Spec (Vue 3.x, TypeScript/JavaScript, common tooling: Vite)
This document is designed as a **security spec** that supports:
1. **Secure-by-default code generation** for new Vue code.
2. **Security review / vulnerability hunting** in existing Vue code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
---
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
* MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session cookies, auth tokens).
* MUST NOT “fix” security by disabling protections (e.g., weakening CSP, turning on unsafe template compilation, using `v-html` as a shortcut, bypassing backend auth, or “just store the token in localStorage”).
* MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and configuration values that justify the claim.
* MUST treat uncertainty honestly: if a protection might exist at the edge (CDN, reverse proxy, WAF, server headers), report it as “not visible in repo; verify runtime/infra config”.
* MUST remember the frontend trust model: **any code shipped to browsers is attacker-readable and attacker-modifiable**. Secrets and “security enforcement” cannot rely on frontend-only logic.
---
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new Vue code or modify existing code:
* MUST follow every **MUST** requirement in this spec.
* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
* MUST prefer safe-by-default framework features and proven libraries over custom security code.
* MUST avoid introducing new risky sinks (runtime template compilation, `v-html` / `innerHTML`, unsafe URL navigation, dynamic script injection, etc.). ([Vue.js][1])
### 1.2 Passive review mode (always on while editing)
While working anywhere in a Vue repo (even if the user did not ask for a security scan):
* MUST “notice” violations of this spec in touched/nearby code.
* SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
* MUST systematically search the codebase for violations of this spec.
* MUST output findings in a structured format (see §2.3).
Recommended audit order:
1. Build/deploy entrypoints and hosting config (Docker, CI, static hosting, SSR server).
2. Secrets exposure (env usage, `.env*`, hard-coded keys). ([vitejs][2])
3. XSS surface: templates, `v-html` / `innerHTML`, URL/style injection, DOM APIs. ([Vue.js][1])
4. Auth/session handling in the browser (token storage, credentialed requests, CSRF integration). ([Vue.js][1])
5. Routing/navigation (open redirects, “return_to/next”, unsafe external navigation). ([Vue.js][1])
6. Third-party scripts and content (CDN assets, analytics, widgets, iframes). ([Vue.js][1])
7. Security headers and browser hardening expectations (CSP, clickjacking). ([Vue.js][1])
8. SSR-specific concerns (state serialization, template boundaries) when applicable. ([Vue.js][1])
---
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
In a Vue app, untrusted input includes (non-exhaustive):
* Anything from APIs: `fetch`, `axios`, GraphQL responses, webhooks, third-party SDKs.
* Router-controlled data: `route.params`, `route.query`, `route.hash`, and anything derived from `window.location`.
* User-controlled persisted content: DB-backed content displayed in the UI (comments, profiles, CMS content).
* Browser-controlled storage: `localStorage`, `sessionStorage`, `IndexedDB`.
* Cross-window messages: `postMessage` inputs.
* Anything that can be influenced by an attacker through DOM clobbering or injected HTML (especially if Vue is mounted onto non-sterile DOM). ([Vue.js][1])
### 2.2 State-changing action (frontend perspective)
An action is state-changing if it can:
* Create/update/delete data via API calls.
* Change authentication/session state (login, logout, refresh token).
* Trigger privileged operations (payments, admin actions).
* Cause side effects (sending emails, triggering webhooks, changing account settings).
### 2.3 Required audit finding format
For each issue found, output:
* Rule ID:
* Severity: Critical / High / Medium / Low
* Location: file path + component/function + line(s)
* Evidence: the exact code/config snippet
* Impact: what could go wrong, who can exploit it
* Fix: safe change (prefer minimal diff)
* Mitigation: defense-in-depth if immediate fix is hard
* False positive notes: what to verify if uncertain
---
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common Vue/front-end misconfigurations.
* MUST ship a **production build** (not a development build or dev server). ([Vue.js][3])
* MUST NOT ship secrets in frontend bundles; treat all client-exposed env variables as public. ([vitejs][2])
* MUST NOT render non-trusted templates or allow user-provided Vue templates (equivalent to arbitrary JS execution). ([Vue.js][1])
* SHOULD avoid raw HTML injection (`v-html`, `innerHTML`) unless content is trusted or strongly sandboxed. ([Vue.js][1])
* SHOULD deploy baseline security headers (especially CSP and clickjacking defenses) at the server/CDN layer. ([OWASP Cheat Sheet Series][4])
* SHOULD use safe auth patterns (prefer HttpOnly cookies for session tokens; coordinate with backend on CSRF). ([Vue.js][1])
---
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### VUE-DEPLOY-001: Do not run dev/preview servers in production
Severity: High
Required:
* MUST NOT deploy the Vite/Vue dev server (`vite`, `npm run dev`, HMR) as the production server.
* MUST NOT use `vite preview` as a production server. ([vitejs][5])
* MUST build (`vite build`) and serve the built assets using a production-grade static server/CDN, or a production SSR server if you are doing SSR. ([vitejs][6])
Insecure patterns:
* Docker/Procfile/systemd running `vite`, `npm run dev`, or `vite preview` as the production entrypoint.
* Publicly exposed HMR endpoints.
Detection hints:
* Search: `vite`, `npm run dev`, `pnpm dev`, `yarn dev`, `vite preview`, `vue-cli-service serve`.
* Check Docker `CMD`, `ENTRYPOINT`, CI deploy scripts, platform config.
Fix:
* Build artifacts with `vite build`.
* Serve `dist/` with hardened hosting (CDN/static server) or integrate into your backend server as static assets.
Notes:
* Using dev/preview servers locally is fine; only flag if it is the production entrypoint.
---
### VUE-DEPLOY-002: Use Vue production builds and keep devtools off in production
Severity: Medium (High if production devtools/debug hooks are enabled)
Required:
* If loading Vue from CDN/self-host without a bundler, MUST use the `.prod.js` builds in production. ([Vue.js][3])
* SHOULD ensure production bundles do not enable Vue devtools in production builds, and SHOULD not intentionally enable production devtools flags. ([Vue.js][7])
Insecure patterns:
* Production includes development build artifacts.
* Explicitly enabling production devtools/diagnostic hooks.
Detection hints:
* Search HTML for `vue.global.js` / non-`.prod.js` variants when using CDN builds.
* Search build config for Vue feature flags like `__VUE_PROD_DEVTOOLS__`. ([Vue.js][7])
Fix:
* Switch to production build artifacts and ensure compile-time flags are configured for production.
---
### VUE-SECRETS-001: Never ship secrets in frontend code or env variables
Severity: High (Critical if real credentials are exposed)
Required:
* MUST treat all frontend code and configuration as public.
* MUST NOT embed secrets in:
* source code
* `.env` files committed to repo
* `import.meta.env.*` variables included in the bundle
* MUST assume any env var that ends up in the client bundle is attacker-readable. ([vitejs][2])
Insecure patterns:
* `VITE_API_KEY=...` containing a true secret (not just a public identifier).
* Hard-coded API keys, private tokens, service credentials, signing keys in JS/TS.
Detection hints:
* Search: `VITE_`, `import.meta.env`, `.env`, `.env.production`, `.env.*.local`.
* Grep for `API_KEY`, `SECRET`, `TOKEN`, `PRIVATE_KEY`, `BEGIN`, `sk-`, `AKIA`, etc.
Fix:
* Move secrets to backend/edge functions.
* Use backend-minted short-lived tokens for the browser when needed.
Notes:
* Vite specifically warns that `.env.*.local` should be gitignored and that `VITE_*` vars end up in the client bundle, so they must not contain sensitive info. ([vitejs][2])
---
### VUE-SECRETS-002: Do not broaden Vite env exposure
Severity: High
Required:
* MUST NOT configure Vite to expose all environment variables to the client.
* SHOULD keep `envPrefix` strict and explicit.
Insecure patterns:
* Setting `envPrefix` to overly broad values (or `''`) to “make env vars work”.
* Custom scripts that inject server secrets into global variables in HTML at build time.
Detection hints:
* Check `vite.config.*` for `envPrefix`.
* Look for `define: { 'process.env': ... }` or manual injection into `window.__CONFIG__`.
Fix:
* Keep secrets server-side.
* Only expose non-sensitive values intentionally designed to be public.
Notes:
* Vite’s docs explain that only prefixed variables are exposed and that exposed variables land in the client bundle. ([vitejs][2])
---
### VUE-XSS-001: Prefer Vue’s default escaping; avoid raw HTML injection
Severity: High
Required:
* MUST rely on Vue’s automatic escaping for text interpolation and attribute binding where possible. ([Vue.js][1])
* MUST NOT render user-provided HTML via:
* `v-html`
* `innerHTML` in render functions / JSX
* direct DOM APIs (`element.innerHTML`, `insertAdjacentHTML`)
unless the HTML is trusted or robustly sanitized and the risk is explicitly accepted. ([Vue.js][1])
Insecure patterns:
* `<div v-html="userProvidedHtml"></div>`
* `h('div', { innerHTML: userProvidedHtml })`
* `<div innerHTML={userProvidedHtml}></div>`
* `el.innerHTML = untrusted`
Detection hints:
* Search: `v-html`, `innerHTML`, `insertAdjacentHTML`, `DOMParser`, `document.write`.
Fix:
* Render untrusted content as text (interpolation).
* If HTML rendering is required (e.g., Markdown), sanitize with a well-maintained HTML sanitizer and apply defense-in-depth (CSP, Trusted Types). ([Vue.js][1])
Notes:
* Vue’s docs explicitly warn that user-provided HTML is never “100% safe” unless sandboxed or strictly self-only exposure. ([Vue.js][1])
---
### VUE-XSS-002: Never use non-trusted templates (client-side template/code injection)
Severity: Critical
Required:
* MUST NOT use non-trusted content as a Vue component template.
* MUST treat “user can write a Vue template” as “user can execute arbitrary JavaScript in your app”, and potentially in SSR contexts too. ([Vue.js][1])
* SHOULD prefer the runtime-only build (templates compiled at build time) and avoid shipping the runtime compiler unless you have a vetted need.
Insecure patterns:
* `createApp({ template: '<div>' + userProvidedString + '</div>' }).mount(...)`
* Storing templates in DB and compiling/rendering them in the browser.
* Admin/CMS features that allow entering Vue template syntax.
Detection hints:
* Search: `template:` where the value is not a static string.
* Search: `@vue/compiler-dom`, `compile(`, “runtime compiler” build selection, dynamic SFC compilation.
* Search for “template editor”, “custom template”, “theme HTML” features.
Fix:
* Treat templates as code: keep them developer-controlled.
* If end-user customization is required, use a safe format (restricted Markdown subset) rendered via a sanitizer, or isolate in a sandboxed iframe.
---
### VUE-XSS-003: Do not mount Vue onto DOM that may contain user-provided server-rendered HTML
Severity: Medium
Required:
* MUST NOT mount Vue on nodes that may contain server-rendered and user-provided content (because attacker-controlled HTML that is “safe as HTML” may become unsafe as a Vue template). ([Vue.js][1])
* SHOULD mount Vue into a “sterile” root element and render the app’s DOM from Vue-controlled templates/components.
Insecure patterns:
* Server renders user content into `#app`, then Vue mounts on `#app` and compiles/interprets that DOM as a template.
* “Sprinkling Vue” on large server-rendered pages that include user-generated content.
Detection hints:
* Check server templates (e.g., Rails/Django/Express templates) for user HTML inserted inside the Vue mount root.
* Look for `mount('#app')` where `#app` includes server-rendered UGC.
Fix:
* Move user-rendered HTML outside the Vue mount root, or render it in a safe way (text/sanitized HTML) from Vue components.
---
### VUE-XSS-004: Prevent URL injection in bindings and navigations
Severity: High
Required:
* MUST validate/sanitize any user-influenced URL before binding to navigation sinks (`href`, `src`, `action`, `window.location`, `window.open`, router navigation to external).
* MUST specifically prevent `javascript:` URL execution in bindings like `<a :href="userProvidedUrl">`. ([Vue.js][1])
* SHOULD validate protocol and destination (allowlist `https:` and expected hosts; allow `mailto:`/`tel:` only if intended).
Insecure patterns:
* `<iframe :src="userProvidedUrl">`
* `window.location = route.query.next`
* `window.open(userProvidedUrl)`
Detection hints:
* Search: `:href=`, `:src=`, `window.location`, `location.href`, `window.open`, `router.push(` with untrusted input.
* Look for `next`, `return_to`, `redirect` query params.
Fix:
* Prefer internal navigation via route names/paths you control.
* For external URLs: parse with `new URL(...)`, allowlist protocol/host, reject `javascript:` and other dangerous schemes.
* Sanitize and validate on the backend before storing user URLs (Vue docs explicitly recommend backend sanitization). ([Vue.js][1])
---
### VUE-XSS-005: Prevent style/CSS injection and UI redress
Severity: Low
Required:
* MUST NOT bind attacker-controlled CSS strings broadly (e.g., `:style="userProvidedStyles"`).
* SHOULD use Vue’s style object syntax and only allow safe, specific properties if user customization is needed. ([Vue.js][1])
* SHOULD isolate “user can control layout/CSS” features inside sandboxed iframes.
Insecure patterns:
* `:style="userProvidedStyles"` where styles are attacker-controlled.
* Rendering user-provided `<style>` content (even if Vue blocks some patterns, don’t try to work around it).
Detection hints:
* Search: `:style="` bound to non-constant variables that originate from API/user content.
* Search for “custom CSS”, “theme editor”, “profile CSS”.
Fix:
* Allowlist properties and values; avoid raw style strings.
* Use sandboxed iframes for rich user customization.
---
### VUE-XSS-006: Never bind user-provided JavaScript into event handler attributes
Severity: Critical
Required:
* MUST NOT bind attacker-provided strings into event handler attributes (e.g., `onclick`, `onfocus`, etc.).
* MUST treat “user-provided JS” as unsafe unless sandboxed and self-only exposure is guaranteed. ([Vue.js][1])
Insecure patterns:
* `<div :onclick="userProvidedString">`
* `<a :onmouseenter="userProvidedString">`
Detection hints:
* Search: `:on` followed by event attribute names (`:onclick`, `:onload`, etc.).
* Search for `setAttribute('on` patterns.
Fix:
* Use real event listeners with developer-controlled handlers.
* If you truly need user scripting, isolate it (sandboxed iframe + strict boundaries).
---
### VUE-ROUTER-001: Do not treat client-side route guards as authorization
Severity: High
Required:
* MUST NOT rely on Vue Router guards, UI hiding, or client-side checks to enforce authorization.
* MUST enforce authorization on the backend for every privileged action and sensitive data response. ([OWASP Cheat Sheet Series][8])
Insecure patterns:
* “Admin route is protected because `beforeEach` checks `user.isAdmin`.”
* Sensitive API endpoints that assume “the frontend won’t call this unless allowed.”
Detection hints:
* Search `router.beforeEach` for role-based gating and see if the backend is also enforcing.
* Look for “security by route meta” patterns (`meta.requiresAdmin`) with no server corroboration.
Fix:
* Keep route guards as UX only (reduce accidental access), but enforce real checks server-side.
---
### VUE-ROUTER-002: Prevent open redirects and unsafe “return_to/next” handling
Severity: Low
Required:
* MUST validate redirect destinations derived from untrusted input (`next`, `return_to`, `redirect`).
* SHOULD allow only same-site relative paths or an explicit allowlist of destinations.
* MUST NOT allow non `http` / `https` protos (such as `javascript:`)
Insecure patterns:
* `router.push(route.query.next as string)`
* `window.location.href = route.query.redirect`
Detection hints:
* Search for `route.query.next`, `route.query.redirect`, `return_to`, `continue`, `callback`.
* Trace the value into router/window navigation sinks.
Fix:
* Allow only relative paths starting with `/` (and reject `//host`, `javascript:`, etc.).
* Prefer redirecting to named routes you control.
Notes:
* Even Vue’s docs note that sanitized URLs still may not guarantee safe destinations. ([Vue.js][1])
---
### VUE-AUTH-001: Token storage must assume XSS is possible
Severity: Low
Required:
* MUST assume any token accessible to JavaScript can be stolen via XSS.
* SHOULD prefer HttpOnly cookies (set by the backend) for session tokens, combined with CSRF protections where relevant. ([Vue.js][1])
* SHOULD avoid storing long-lived tokens (especially refresh tokens) in `localStorage`/`sessionStorage`.
Insecure patterns:
* `localStorage.setItem('token', ...)` for long-lived bearer tokens.
* Storing refresh tokens in JS-accessible storage.
Detection hints:
* Search: `localStorage`, `sessionStorage`, `indexedDB`, `persist`, `pinia-plugin-persistedstate`.
* Identify whether stored values are auth/session material.
Fix:
* Prefer backend-managed sessions via HttpOnly cookies.
* If bearer tokens are unavoidable, keep them short-lived, stored in memory, and rotate frequently; combine with strong XSS mitigations (CSP, Trusted Types, strict sanitization). ([OWASP Cheat Sheet Series][4])
---
### VUE-CSRF-001: Coordinate with the backend for CSRF when using cookies
Severity: High (for cookie-authenticated state-changing requests)
NOTE: If the application is not using cookie based authentication (for example if it passes an Authorization header), then CSRF is not a concern
Required:
* If API requests include cookies (`credentials: 'include'` / `withCredentials: true`) and cookies authenticate the user, MUST include CSRF protections coordinated with the backend (token/header patterns, Origin checks, SameSite cookies as defense-in-depth). ([Vue.js][1])
* MUST NOT “solve CORS/CSRF errors” by disabling protections on the backend or using `mode: 'no-cors'` on the frontend.
Insecure patterns:
* `fetch(url, { credentials: 'include', method: 'POST', body: ... })` with no CSRF token/header usage anywhere.
* Enabling cross-origin credentialed requests without strict origin allowlists (backend-side).
Detection hints:
* Search: `credentials: 'include'`, `withCredentials`, `xsrf`, `csrf`, `X-CSRF-Token`, `X-XSRF-TOKEN`.
* Look at API wrapper modules for headers and cookie settings.
Fix:
* Implement backend-issued CSRF tokens and require them on state-changing requests.
* Keep cookies `SameSite=Lax/Strict` where compatible and verify Origin/Referer where appropriate (backend-driven). ([OWASP Cheat Sheet Series][9])
Notes:
* Vue’s docs explicitly say CSRF is primarily backend-addressed but recommends coordinating on CSRF token submission. ([Vue.js][1])
---
### VUE-HTTP-001: Do not put secrets in URLs; avoid leaking sensitive data in navigation/logs
Severity: Medium
Required:
* MUST NOT place tokens/secrets in query strings or fragments (they leak via logs, referrers, browser history).
* SHOULD avoid logging sensitive values to console in production.
Insecure patterns:
* `/?token=...`, `/#access_token=...` used beyond short-lived OAuth handoff.
* `console.log(userSession)` that includes tokens/PII.
Detection hints:
* Search for `token=` in router parsing, auth callback handlers, and analytics logs.
* Search for `console.log(` around auth code.
Fix:
* Use Authorization headers or HttpOnly cookies.
* Scrub logs; gate debug logs behind dev-only checks.
---
### VUE-HEADERS-001: Require security headers at the deployment layer
Severity: Medium
Required:
* SHOULD deploy a CSP (`Content-Security-Policy`) suitable for your Vue app.
* SHOULD deploy clickjacking defenses (CSP `frame-ancestors` and/or `X-Frame-Options`) unless intentional embedding is required.
* SHOULD deploy `X-Content-Type-Options: nosniff`, plus other headers as appropriate (Referrer-Policy, Permissions-Policy). ([OWASP Cheat Sheet Series][4])
Insecure patterns:
* No evidence of headers in server/CDN config for an app with UGC or rich HTML rendering.
* CSP includes `unsafe-inline`/`unsafe-eval` without strong justification.
Detection hints:
* Look for hosting config: nginx, Netlify/Vercel headers config, CloudFront/Cloudflare rules.
* If absent in repo, flag as “verify at edge”.
Fix:
* Set headers at the edge or in the server. Start with a conservative CSP and tighten.
---
### VUE-CSP-001: Use Trusted Types and DOM XSS hardening when feasible
Severity: Low
Required:
* For apps with significant DOM injection surface (rich text, plugins, `v-html`), SHOULD consider enabling Trusted Types to reduce DOM XSS risk. ([web.dev][10])
* SHOULD treat Trusted Types as defense-in-depth, not a replacement for sanitization.
Insecure patterns:
* Frequent use of `innerHTML`/`v-html` without sanitization or CSP hardening.
Detection hints:
* Search: `v-html`, `innerHTML`, `insertAdjacentHTML`.
* Check CSP for `require-trusted-types-for 'script'` usage (if headers are in repo).
Fix:
* Reduce/centralize HTML injection, sanitize inputs, and add Trusted Types policies where appropriate.
---
### VUE-THIRDPARTY-001: Avoid dynamic third-party script injection; prefer static, vetted loading
Severity: Low
Required:
* MUST NOT inject `<script src="...">` where the URL is user-controlled.
* SHOULD treat third-party widgets/analytics as supply-chain risk; load only from vetted, pinned sources.
Insecure patterns:
* `const s=document.createElement('script'); s.src = userProvidedUrl; ...`
* “Plugin marketplace” that loads arbitrary remote scripts.
Detection hints:
* Search: `createElement('script')`, `.src =`, `appendChild(script)`.
* Search for “loadExternalScript”, “injectScript”, “cdnUrl”.
Fix:
* Bundle dependencies, or allowlist strict origins and enforce integrity (see SRI rule).
* Consider sandboxed iframes for untrusted third-party UI.
---
### VUE-SRI-001: Use Subresource Integrity for CDN-hosted scripts/styles
Severity: Low
Required:
* If loading scripts/styles from a CDN, SHOULD use Subresource Integrity (`integrity` attribute) with appropriate `crossorigin` configuration. ([MDN Web Docs][11])
* SHOULD prefer self-hosting or bundling over runtime CDN dependencies for security-critical code.
Insecure patterns:
* `<script src="https://cdn.example/...">` with no `integrity`.
* Remote script URLs that can change content without version pinning.
Detection hints:
* Search `index.html` and server templates for `https://` script/style tags.
* Check for `integrity=`.
Fix:
* Add SRI hashes (and pin versions), or bundle assets with your build.
---
### VUE-SUPPLY-001: Dependency and patch hygiene is mandatory
Severity: Low
Required:
* SHOULD keep Vue and official companion libraries updated; Vue explicitly recommends using latest versions to remain as secure as possible. ([Vue.js][1])
* MUST respond to security advisories promptly.
* SHOULD pin dependencies and keep lockfiles committed (to reduce drift in production artifacts).
Insecure patterns:
* Outdated major versions with known CVEs.
* No lockfile in repo; wide semver ranges for critical deps.
* Ignoring advisories for template/rendering/compiler packages.
Detection hints:
* Inspect `package.json`, lockfiles, CI install commands.
* Search for `npm audit` disabled, “ignore vulnerabilities” scripts.
Fix:
* Upgrade dependencies and add regression tests around the impacted behavior.
* Add dependency scanning in CI.
---
### VUE-SSR-001: SSR adds additional trust boundaries; treat state injection as XSS-sensitive
Severity: Medium
Required:
* When using SSR, MUST treat anything injected into the HTML document (initial state, serialized data, inline scripts) as XSS-sensitive.
* MUST keep the “trusted templates only” rule even stricter, because unsafe templates can lead to server-side execution during rendering. ([Vue.js][1])
* SHOULD follow Vue SSR documentation and best practices for SSR security. ([Vue.js][1])
Insecure patterns:
* Concatenating untrusted strings into SSR templates.
* Injecting JSON into `<script>` blocks without robust escaping/serialization controls.
Detection hints:
* Search server code for `__INITIAL_STATE__`, `window.__*STATE__`, template concatenation, and SSR render pipelines.
* Trace untrusted data into those sinks.
Fix:
* Use safe serialization patterns recommended by your SSR stack.
* Avoid rendering untrusted HTML; sanitize or isolate.
---
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
* Dev/preview servers in production:
* `npm run dev`, `vite`, `vite preview`, `vue-cli-service serve` ([vitejs][5])
* Secrets exposure:
* `.env`, `.env.production`, `.env.*.local`, `VITE_`, `import.meta.env`, hard-coded `API_KEY` / `SECRET` ([vitejs][2])
* XSS sinks:
* `v-html`, `innerHTML`, `insertAdjacentHTML`, `DOMParser`, `document.write` ([Vue.js][1])
* Client-side template injection:
* `template:` concatenation, `compile(`, runtime compiler usage, mounting on non-sterile DOM ([Vue.js][1])
* URL injection / open redirects:
* `:href="..."` / `:src="..."` from user data
* `javascript:` occurrences
* `route.query.next` / `redirect` / `return_to` flowing into `router.push` or `window.location` ([Vue.js][1])
* Style injection:
* `:style="userProvidedStyles"` or user-driven theme CSS ([Vue.js][1])
* Token storage:
* `localStorage.setItem('token'...)`, persisted auth stores, refresh tokens in JS-accessible storage
* CSRF integration red flags:
* `credentials: 'include'` / `withCredentials: true` without any CSRF header/token handling ([Vue.js][1])
* Third-party scripts:
* dynamic script injection (`createElement('script')`), CDN scripts without SRI ([MDN Web Docs][11])
* External links security:
* `target="_blank"` without `rel="noopener"`/`noreferrer` (still recommended for legacy and explicitness) ([MDN Web Docs][12])
Always try to confirm:
* data origin (untrusted vs trusted)
* sink type (HTML/DOM insertion, template compilation, URL navigation, style injection, script injection)
* protective controls present (sanitization, allowlists, CSP/Trusted Types, backend validation)
---
## 6) Sources (accessed 2026-01-27)
Primary Vue documentation:
* Vue Docs: Security — `https://vuejs.org/guide/best-practices/security` ([Vue.js][1])
* Vue Docs: Template Syntax (security warning about in-DOM templates) — `https://vuejs.org/guide/essentials/template-syntax` ([Vue.js][13])
* Vue Docs: Production Deployment — `https://vuejs.org/guide/best-practices/production-deployment` ([Vue.js][3])
* Vue Docs: Feature Flags — `https://link.vuejs.org/feature-flags` ([Vue.js][7])
Vite documentation (common Vue tooling):
* Vite Docs: Env Variables and Modes (VITE_* exposure + security notes) — `https://vite.dev/guide/env-and-mode` ([vitejs][2])
* Vite Docs: CLI (`vite preview` not designed for production) — `https://vite.dev/guide/cli` ([vitejs][5])
* Vite Docs: Server Options (`server.host` can listen on public addresses) — `https://vite.dev/config/server-options` ([vitejs][14])
OWASP and web platform hardening references:
* OWASP Cheat Sheet Series: XSS Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html` ([Vue.js][1])
* OWASP Cheat Sheet Series: CSRF Prevention — `https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][9])
* OWASP Cheat Sheet Series: Authorization — `https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][8])
* OWASP Cheat Sheet Series: HTTP Headers — `https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html` ([OWASP Cheat Sheet Series][4])
* HTML5 Security Cheat Sheet (referenced by Vue) — `https://html5sec.org/` ([Vue.js][1])
Browser/platform references:
* MDN: `rel="noopener"` — `https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener` ([MDN Web Docs][12])
* MDN: Subresource Integrity — `https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity` ([MDN Web Docs][11])
* web.dev: Trusted Types — `https://web.dev/trusted-types/` ([web.dev][10])
[1]: https://vuejs.org/guide/best-practices/security "https://vuejs.org/guide/best-practices/security"
[2]: https://vite.dev/guide/env-and-mode "https://vite.dev/guide/env-and-mode"
[3]: https://vuejs.org/guide/best-practices/production-deployment "https://vuejs.org/guide/best-practices/production-deployment"
[4]: https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html"
[5]: https://vite.dev/guide/cli "https://vite.dev/guide/cli"
[6]: https://vite.dev/guide/build "https://vite.dev/guide/build"
[7]: https://vuejs.org/guide/best-practices/production-deployment?utm_source=chatgpt.com "Production Deployment"
[8]: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html"
[9]: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html "https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html"
[10]: https://web.dev/articles/trusted-types "https://web.dev/articles/trusted-types"
[11]: https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity?utm_source=chatgpt.com "Subresource Integrity - Security - MDN Web Docs"
[12]: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener"
[13]: https://vuejs.org/guide/essentials/template-syntax "Template Syntax | Vue.js"
[14]: https://vite.dev/config/server-options "https://vite.dev/config/server-options"
.blackbox/skills/security-best-practices/references/python-django-web-server-security.md
+882
View File
@@ -0,0 +1,882 @@
# Django (Python) Web Security Spec (Django 6.0.x, Python 3.x)
This document is designed as a **security spec** that supports:
1. **Secure-by-default code generation** for new Django code.
2. **Security review / vulnerability hunting** in existing Django code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
---
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
* MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session cookies, `SECRET_KEY`, `SECRET_KEY_FALLBACKS`, database passwords).
* MUST NOT “fix” security by disabling protections (e.g., removing `CsrfViewMiddleware`, sprinkling `@csrf_exempt`, loosening `ALLOWED_HOSTS` to `['*']`, disabling `SecurityMiddleware`, disabling template auto-escaping, disabling permission checks).
* MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and concrete configuration values that justify the claim.
* MUST treat uncertainty honestly: if a protection might exist in infrastructure (reverse proxy, WAF, CDN, ingress controller), report it as “not visible in app code; verify at runtime / edge config”.
* MUST keep fixes compatible with Django’s intended security model: prefer Django’s built-ins (middleware, auth, forms, ORM) over custom security logic whenever possible. Django’s deployment checklist and system checks are part of the intended model. ([Django Project][1])
---
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new Django code or modify existing code:
* MUST follow every **MUST** requirement in this spec.
* SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
* MUST prefer safe-by-default Django APIs and proven libraries over custom security code.
* MUST avoid introducing new risky sinks (dynamic template rendering from untrusted strings, unsafe redirects, unsafe file serving, shell execution, raw SQL string formatting, SSRF-capable URL fetchers from untrusted input).
### 1.2 Passive review mode (always on while editing)
While working anywhere in a Django repo (even if the user did not ask for a security scan):
* MUST “notice” violations of this spec in touched/nearby code.
* SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
* MUST systematically search the codebase for violations of this spec.
* MUST output findings in a structured format (see §2.3).
Recommended audit order:
1. Deployment entrypoints (ASGI/WSGI), Dockerfiles, Procfiles, systemd units, platform manifests.
2. `settings.py` and environment-specific settings modules.
3. Middleware ordering and enabled protections.
4. Authn/authz (login, session management, permissions, admin).
5. CSRF protections and state-changing endpoints.
6. Templates and XSS.
7. File handling (uploads/downloads/static/media) and path traversal.
8. Injection classes (SQL, command execution, unsafe deserialization).
9. Outbound requests (SSRF).
10. Redirect handling (open redirects) + CORS + security headers (CSP, HSTS, etc.).
11. Dependency/pinning and patch posture.
---
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
* `request.GET`, `request.POST`, `request.FILES`
* `request.body`, JSON bodies (e.g., `json.loads(request.body)`), DRF `request.data`
* URL path parameters (e.g., `<int:id>`, `<slug:...>`)
* `request.headers` / `request.META` (including `HTTP_HOST`, `HTTP_ORIGIN`, `HTTP_REFERER`, `HTTP_X_FORWARDED_*`)
* `request.COOKIES`
* Any data from external systems (webhooks, third-party APIs, message queues)
* Any persisted content that originated from users (DB rows, cached content, file uploads)
Django explicitly emphasizes “never trust user-controlled data” and recommends using forms/validation. ([Django Project][2])
### 2.2 State-changing request
A request is state-changing if it can create/update/delete data, change auth/session state, trigger side effects (purchase, email send, webhook send), or initiate privileged actions.
### 2.3 Required audit finding format
For each issue found, output:
* Rule ID:
* Severity: Critical / High / Medium / Low
* Location: file path + function/class/view name + line(s)
* Evidence: the exact code/config snippet
* Impact: what could go wrong, who can exploit it
* Fix: safe change (prefer minimal diff)
* Mitigation: defense-in-depth if immediate fix is hard
* False positive notes: what to verify if uncertain
---
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common Django misconfigurations. Django provides a “Deployment checklist” and recommends running `manage.py check --deploy` against production settings. ([Django Project][1])
### 3.1 Settings management pattern (SHOULD)
* SHOULD use environment-based configuration (or a secret manager) so production settings are not hard-coded.
* MUST treat sensitive settings as confidential (e.g., `SECRET_KEY`, DB passwords) and keep them out of source control. Django’s checklist explicitly recommends loading `SECRET_KEY` from env or a file rather than hardcoding. ([Django Project][1])
* SHOULD separate dev vs prod settings modules, with safe defaults for production (fail closed if critical settings are missing). ([Django Project][1])
### 3.2 Minimum baseline targets (production)
* MUST NOT use `manage.py runserver` as the production entrypoint; use a production-ready WSGI or ASGI server. ([Django Project][1])
* MUST set `DEBUG = False` in production. ([Django Project][1])
* MUST set a strong, secret `SECRET_KEY` and keep it secret; MAY use `SECRET_KEY_FALLBACKS` for safe rotation. ([Django Project][1])
* MUST set `ALLOWED_HOSTS` to expected hosts (no wildcard unless you do your own host validation). ([Django Project][1])
* MUST enforce HTTPS for authenticated areas (ideally site-wide for any login-capable app) and set `CSRF_COOKIE_SECURE=True` and `SESSION_COOKIE_SECURE=True` when HTTPS is used. ([Django Project][1])
* SHOULD enable key `SecurityMiddleware` headers/settings: HSTS, Referrer-Policy, COOP, nosniff, SSL redirect (with correct proxy configuration). ([Django Project][3])
* MUST treat user uploads as untrusted; ensure your web server never interprets them as executable content; keep `MEDIA_ROOT` separate from `STATIC_ROOT`. ([Django Project][1])
---
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### DJANGO-DEPLOY-001: Do not use Django’s development server in production
Severity: High (if production)
Required:
* MUST NOT deploy `manage.py runserver` as the production server.
* MUST run behind a production-grade WSGI or ASGI server. ([Django Project][1])
Insecure patterns:
* Production docs/scripts using `python manage.py runserver 0.0.0.0:8000`.
* Docker `CMD`/entrypoint uses `runserver`.
* Kubernetes/Procfile/systemd units invoking `runserver`.
Detection hints:
* Search for `manage.py runserver`, `runserver 0.0.0.0`, `--insecure`.
* Check Docker `CMD/ENTRYPOINT`, Procfile, systemd unit files, Helm charts.
Fix:
* Use a production server (WSGI/ASGI) as recommended in Django’s deployment checklist. ([Django Project][1])
Note:
* `runserver` is fine for local development. Only flag if it’s used as the production entrypoint.
---
### DJANGO-DEPLOY-002: `DEBUG` MUST be disabled in production
Severity: High
Required:
* MUST set `DEBUG = False` in production.
* MUST treat any mechanism that exposes debug pages/tracebacks to untrusted users as a critical information disclosure risk. Django’s checklist explicitly warns `DEBUG=True` leaks source excerpts, local variables, settings, and more. ([Django Project][1])
Insecure patterns:
* `DEBUG = True` in production settings.
* Environment defaults to `DEBUG=True` unless explicitly overridden.
Detection hints:
* Search `DEBUG = True`, `DEBUG=os.environ.get(..., True)`, `DJANGO_DEBUG`, `.env` files.
* Look for “production” settings modules that import from dev defaults.
Fix:
* Set `DEBUG=False` in prod settings; use explicit environment config.
* Ensure error reporting is via safe logging/monitoring, not debug pages. ([Django Project][1])
---
### DJANGO-CONFIG-001: `SECRET_KEY` must be strong, secret, and rotated safely
Severity: High (Critical if missing in production with signing/sessions)
Required:
* MUST set a large random `SECRET_KEY` in production and keep it secret. ([Django Project][1])
* MUST NOT commit it to source control or print/log it. ([Django Project][1])
* SHOULD load it from env or a file/secret store (not hard-coded). ([Django Project][1])
* MAY rotate keys using `SECRET_KEY_FALLBACKS` to avoid instantly invalidating all signed data; MUST remove old keys from fallbacks in a timely manner. ([Django Project][1])
Insecure patterns:
* Hard-coded `SECRET_KEY = "..."` in repo for production.
* `SECRET_KEY` reused across environments.
* `SECRET_KEY_FALLBACKS` contains long-expired keys indefinitely.
Detection hints:
* Search for `SECRET_KEY =`, `SECRET_KEY_FALLBACKS`, `.env` committed files, `print(settings.SECRET_KEY)`.
Fix:
* Load from secret manager / environment variable.
* If rotating:
* Set new `SECRET_KEY`
* Keep old key(s) temporarily in `SECRET_KEY_FALLBACKS`
* Remove old key(s) after the rotation window. ([Django Project][1])
---
### DJANGO-HOST-001: Host header must be validated (`ALLOWED_HOSTS` must be strict)
Severity: Medium
Required:
* MUST set `ALLOWED_HOSTS` in production to your expected domains/hosts. ([Django Project][1])
* MUST NOT set `ALLOWED_HOSTS = ['*']` in production unless you also implement your own robust `Host` validation (Django warns that wildcards require your own validation to avoid CSRF-class attacks). ([Django Project][1])
* SHOULD configure the fronting web server to reject unknown hosts early (defense-in-depth). ([Django Project][1])
Insecure patterns:
* `ALLOWED_HOSTS = ['*']` (or env expands to `*`) in production.
* `ALLOWED_HOSTS = []` with `DEBUG=False` (site won’t run, or misconfigured deployments attempt workarounds).
Detection hints:
* Search `ALLOWED_HOSTS`.
* Check platform environment settings that override `ALLOWED_HOSTS`.
Fix:
* Set `ALLOWED_HOSTS = ['example.com', 'www.example.com', ...]` for prod.
* Keep dev hosts separate.
Notes:
* Django uses the Host header for URL construction; fake Host values can lead to CSRF, cache poisoning, and poisoned email links (Django security docs call this out). ([Django Project][2])
---
### DJANGO-HTTPS-001: If TLS is used cookie transport must be secured
Severity: High (Critical for auth-enabled apps)
NOTE: Only enforce this if TLS is enabled, as it will break non-TLS applications
If using TLS:
* MUST set:
* `CSRF_COOKIE_SECURE = True` ([Django Project][1])
* `SESSION_COOKIE_SECURE = True` ([Django Project][1])
* SHOULD consider enabling:
* `SECURE_SSL_REDIRECT = True` (with correct proxy config) ([Django Project][3])
* HSTS via `SECURE_HSTS_SECONDS` (+ includeSubDomains/preload as appropriate). ([Django Project][3])
Insecure patterns:
* Login pages over HTTP, or mixed HTTP/HTTPS with the same session cookie.
* `CSRF_COOKIE_SECURE=False` or `SESSION_COOKIE_SECURE=False` in production HTTPS.
* HSTS enabled incorrectly (can break site for the duration).
Detection hints:
* Inspect `settings.py` for `CSRF_COOKIE_SECURE`, `SESSION_COOKIE_SECURE`, `SECURE_SSL_REDIRECT`, `SECURE_HSTS_SECONDS`.
* Inspect proxy/ingress config for HTTP->HTTPS redirect behavior.
Fix:
* Enable HTTPS redirect and secure cookies.
* Add HSTS carefully (start with low value, validate, then increase). Django warns misconfig can break your site for the HSTS duration. ([Django Project][3])
---
### DJANGO-PROXY-001: Reverse proxy trust must be configured correctly (`SECURE_PROXY_SSL_HEADER`)
Severity: Medium (when behind a TLS proxy)
Required:
* If behind a reverse proxy that terminates TLS, MUST configure Django so `request.is_secure()` reflects the *external* scheme, otherwise CSRF and other logic can break. Django documents using `SECURE_PROXY_SSL_HEADER` for this. ([Django Project][3])
* MUST only set `SECURE_PROXY_SSL_HEADER` if you control the proxy (or have guarantees) and it strips inbound spoofed headers. Django explicitly warns misconfig can compromise security and lists required conditions. ([Django Project][3])
Insecure patterns:
* `SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")` in an environment where the proxy does not strip user-supplied `X-Forwarded-Proto`.
* Infinite redirect loops after setting `SECURE_SSL_REDIRECT=True` (often indicates proxy HTTPS detection is wrong). ([Django Project][3])
Detection hints:
* Search `SECURE_PROXY_SSL_HEADER`, `SECURE_SSL_REDIRECT`.
* Inspect ingress/proxy behavior for stripping forwarded headers.
Fix:
* Set `SECURE_PROXY_SSL_HEADER` only if the proxy strips and sets the header correctly (per Django’s documented prerequisites). ([Django Project][3])
---
### DJANGO-SESS-001: Session cookies must use secure attributes in production
Severity: Medium (Only if TLS enabled)
Required (production, HTTPS):
* MUST set `SESSION_COOKIE_SECURE=True` (only transmit over HTTPS). ([Django Project][3])
* MUST keep `SESSION_COOKIE_HTTPONLY=True` (Django default is `True`). ([Django Project][3])
* SHOULD keep `SESSION_COOKIE_SAMESITE='Lax'` (Django default is `Lax`) unless a justified cross-site flow requires `None`. ([Django Project][3])
* SHOULD avoid setting `SESSION_COOKIE_DOMAIN` unless you truly need cross-subdomain cookies (subdomain-wide cookies expand attack surface).
Insecure patterns:
* `SESSION_COOKIE_SECURE=False` in production HTTPS.
IMPORTANT NOTE: Only set `Secure` in production environment when TLS is configured. When running in a local dev environment over HTTP, do not set `Secure` property on cookies. You should do this conditionally based on if the app is running in production mode. You should also include a property like `SESSION_COOKIE_SECURE` which can be used to disable `Secure` cookies when testing over HTTP.
* `SESSION_COOKIE_HTTPONLY=False`.
* `SESSION_COOKIE_SAMESITE=None` combined with cookie-authenticated state-changing endpoints (higher CSRF risk).
Detection hints:
* Search for `SESSION_COOKIE_` settings, `response.set_cookie(..., httponly=..., secure=..., samesite=...)`.
Fix:
* Set the above explicitly in production settings.
* Validate compatibility with your auth flows. ([Django Project][3])
---
### DJANGO-SESS-002: CSRF cookie settings must be deliberate (HttpOnly has tradeoffs)
Severity: Medium
Required:
* SHOULD set `CSRF_COOKIE_SECURE=True` when using HTTPS/TLS. ([Django Project][3])
* SHOULD keep `CSRF_COOKIE_SAMESITE='Lax'` unless you have a cross-site requirement. Django default is `Lax`. ([Django Project][3])
* MAY set `CSRF_COOKIE_HTTPONLY=True` (default is `False`) if your frontend does not need to read the CSRF cookie. If you enable it, your JS must read the CSRF token from the DOM instead (Django documents this). ([Django Project][3])
Insecure patterns:
* `CSRF_COOKIE_SECURE=False` in production HTTPS/TLS.
* Setting `CSRF_COOKIE_HTTPONLY=True` but still relying on “read csrftoken cookie in JS” patterns (breaks CSRF for AJAX).
* `CSRF_COOKIE_SAMESITE=None` without a clear reason.
Detection hints:
* Search for `CSRF_COOKIE_` settings.
* Search JS for `document.cookie` usage to fetch `csrftoken`.
Fix:
* Align cookie settings with your CSRF token acquisition method (cookie vs DOM) as Django describes. ([Django Project][4])
---
### DJANGO-CSRF-001: Cookie-authenticated state-changing requests MUST be CSRF-protected
Severity: High
Required:
* MUST keep `django.middleware.csrf.CsrfViewMiddleware` enabled (it is activated by default). ([Django Project][4])
* MUST include `{% csrf_token %}` in internal POST forms; MUST NOT include it in forms that POST to external URLs (Django warns this leaks the token). ([Django Project][4])
* MUST protect all state-changing endpoints (POST/PUT/PATCH/DELETE) that rely on cookies for authentication.
* For AJAX/SPA calls, MUST send the CSRF token via the `X-CSRFToken` header (or configured header name) as documented. ([Django Project][4])
* MUST be very careful with `@csrf_exempt` and use it only when absolutely necessary; if used, MUST replace CSRF with an appropriate alternative control (e.g., request signing for webhooks). Django explicitly warns about `csrf_exempt`. ([Django Project][2])
Insecure patterns:
* Missing `CsrfViewMiddleware` in `MIDDLEWARE`.
* `@csrf_exempt` on general-purpose authenticated views.
* POST/PUT/PATCH/DELETE endpoints with session auth and no CSRF tokens.
* Using GET for state-changing actions (amplifies CSRF risk).
Detection hints:
* Inspect `settings.py` `MIDDLEWARE` for `CsrfViewMiddleware` and its order (Django notes it should come before middleware that assumes CSRF is handled). ([Django Project][4])
* Search for `csrf_exempt`, `csrf_protect`, `ensure_csrf_cookie`.
* Enumerate URL patterns for non-GET methods; confirm CSRF coverage.
Fix:
* Re-enable `CsrfViewMiddleware`, add CSRF tokens to forms, and add AJAX header handling.
* For caching decorators: if you cache a view that needs CSRF tokens, apply `@csrf_protect` as Django documents to avoid caching a response without CSRF cookie/Vary headers. ([Django Project][4])
Notes:
* When deployed with HTTPS, Django’s CSRF middleware also checks the Referer header for same-origin (Django security docs mention this). ([Django Project][2])
---
### DJANGO-XSS-001: Prevent reflected/stored XSS in templates and HTML generation
Severity: High
Required:
* MUST rely on Django template auto-escaping (safe-by-default) for HTML templates. Django security docs highlight that Django templates escape dangerous characters but have limitations. ([Django Project][2])
* MUST NOT disable auto-escaping broadly (`{% autoescape off %}`) unless the content is trusted or safely sanitized. ([Django Project][5])
* MUST NOT mark untrusted content as safe:
* Avoid `mark_safe(...)` on user data.
* Avoid `|safe` on user-controlled content.
* MUST be careful about HTML context pitfalls (e.g., unquoted attributes); Django explicitly shows an example where escaping does not protect an unquoted attribute context. ([Django Project][2])
* SHOULD prefer safe HTML construction helpers (e.g., `format_html`) rather than manual concatenation that risks missing escapes. ([Django Project][6])
Insecure patterns:
* `{% autoescape off %}{{ user_input }}{% endautoescape %}`
* `{{ user_input|safe }}`
* `mark_safe(request.GET["q"])`
* Unquoted attribute injections: `<style class={{ var }}>...` (Django’s own example). ([Django Project][2])
Detection hints:
* Search templates for `|safe`, `autoescape off`, `safeseq`.
* Search Python for `mark_safe`, `SafeString`, or direct HTML concatenation with request/DB values.
* Review any code returning `HttpResponse(user_value)` where `user_value` contains HTML.
Fix:
* Remove unsafe marking; sanitize only when strictly necessary (use an allowlist-based HTML sanitizer).
* Quote attributes and avoid placing untrusted values into dangerous contexts.
* Add CSP as defense-in-depth (see DJANGO-CSP-001). ([Django Project][2])
---
### DJANGO-TEMPLATE-001: Never render untrusted template source strings
Severity: High to Critical (depends on context and exposure)
Required:
* MUST NOT render templates where the template source string is influenced by untrusted input (request, user content, DB rows editable by untrusted users).
* MUST treat “template from string” patterns as dangerous, even if Django templates are more constrained than some other engines: they can still leak data from context, bypass escaping, and create XSS or content injection.
Insecure patterns:
* `Template(request.GET["tmpl"]).render(Context(...))`
* Saving user templates in the DB and rendering them with normal privileges/context.
Detection hints:
* Search for `django.template.Template(`, `Engine.from_string`, `.render(Context(` with non-constant strings.
* Trace where the template string comes from (admin panels, DB, uploads, requests).
Fix:
* Replace with non-executing formatting (e.g., `string.Template`, explicit placeholders) or a strict allowlisted rendering model.
* If you *must* support user-defined templates, isolate heavily (separate service/tenant context, strict allowlists, and assume bypasses are possible).
---
### DJANGO-SQL-001: Prevent SQL injection (use ORM or parameterized raw SQL)
Severity: High
Required:
* MUST use Django ORM/querysets for normal DB access; Django notes querysets are parameterized and protected from SQL injection under typical use. ([Django Project][2])
* MUST be very careful with raw SQL; if using `raw()`, `cursor.execute()`, `extra()`, or `RawSQL`, MUST pass parameters separately (e.g., `params=`) and MUST NOT string-interpolate untrusted input into SQL. Django’s raw SQL docs warn to escape user-controlled parameters using `params`. ([Django Project][7])
* MUST NOT quote placeholders in SQL templates (Django docs explicitly warn that quoting `%s` placeholders makes it unsafe). ([Django Project][8])
* SHOULD avoid `extra()` and `RawSQL` unless necessary; Django security docs call for caution. ([Django Project][2])
Insecure patterns:
* `cursor.execute(f"SELECT ... WHERE id={request.GET['id']}")`
* `Model.objects.raw("... %s" % user_input)` (string formatting)
* `extra(where=[f"headline='{q}'"])`
* Quoted placeholders: `WHERE othercol = '%s'` (explicitly documented as unsafe). ([Django Project][8])
Detection hints:
* Grep for `.raw(`, `.extra(`, `RawSQL(`, `connection.cursor()`, `.execute(`.
* Grep for SQL keywords (`SELECT`, `UPDATE`, `DELETE`, `INSERT`) in Python strings.
* Track untrusted inputs into these call sites.
Fix:
* Prefer ORM queries.
* If raw SQL is unavoidable, use parameters (`params`, DB-API param binding) and do not quote placeholders. ([Django Project][7])
---
### DJANGO-CMD-001: Prevent OS command injection
Severity: Critical to High (depends on exposure)
Required:
* MUST avoid executing system commands with attacker-influenced input.
* If subprocess is necessary:
* MUST pass args as a list (not a shell string).
* MUST NOT use `shell=True` with attacker-influenced content.
* SHOULD use strict allowlists for variable components.
* SHOULD prefer pure-Python libraries instead of shelling out.
Insecure patterns:
* `os.system(request.GET["cmd"])`
* `subprocess.run(f"convert {path}", shell=True)` where `path` is user-controlled.
Detection hints:
* Search `os.system`, `subprocess`, `Popen`, `shell=True`.
* Trace request/DB inputs into those calls.
Fix:
* Replace with library APIs; if unavoidable, hard-code executable and allowlist validated parameters.
---
### DJANGO-UPLOAD-001: File uploads must be validated, stored safely, and served safely
Severity: High
Required:
* MUST treat all user uploads as untrusted. Django explicitly warns “Media files are uploaded by your users. They’re untrusted!” ([Django Project][1])
* MUST ensure the web server never interprets user uploads as executable code (e.g., don’t allow uploaded `.php` or HTML to execute/inline as active content). ([Django Project][1])
* MUST enforce size limits (at least at the web server; Django security docs recommend limiting upload size at the server to prevent DoS). ([Django Project][2])
* SHOULD validate file types using allowlists and content checks (not only extensions).
* SHOULD store uploads outside the application code directory and outside any static root.
* SHOULD consider serving uploads from a separate top-level/second-level domain to reduce same-origin impact; Django security docs recommend a distinct domain and note that a subdomain may be insufficient for some protections. ([Django Project][2])
* MUST be aware of polyglot upload risks: Django documents a case where HTML can be uploaded “as an image” by using a valid PNG header (and may be served as HTML depending on the web server). ([Django Project][2])
Insecure patterns:
* Serving uploads inline with `text/html` or without forcing download for potentially active formats.
* Upload allowlist based only on extension.
* Upload storage inside static roots or code roots.
Detection hints:
* Search for `request.FILES`, `FileField`, `ImageField`, upload forms/views.
* Inspect upload serving paths and Nginx/Apache config (media handlers).
* Check `MEDIA_URL`, `MEDIA_ROOT`, and static config.
Fix:
* Configure the web server to serve uploads as inert bytes (no execution), and consider forcing `Content-Disposition: attachment` for risky types.
* Use a separate domain for user content when warranted. ([Django Project][2])
---
### DJANGO-PATH-001: Prevent path traversal and unsafe file serving (static/media separation)
Severity: High
Required:
* MUST NOT treat user input as a filesystem path for reads/writes/serving.
* MUST keep `MEDIA_ROOT` and `STATIC_ROOT` distinct; Django settings docs explicitly warn they must have different values to avoid security implications. ([Django Project][3])
* SHOULD prefer using Django storage APIs keyed by server-side identifiers rather than accepting arbitrary relative paths from users.
Insecure patterns:
* `open(os.path.join(MEDIA_ROOT, request.GET["path"]))`
* Download endpoints that take `?file=../../...` style parameters.
* Misconfigured `MEDIA_ROOT == STATIC_ROOT`.
Detection hints:
* Grep for `open(`, `Path(`, `os.path.join(` used with request values.
* Check `MEDIA_ROOT`, `STATIC_ROOT` in settings. ([Django Project][3])
Fix:
* Use server-side IDs mapped to known files.
* Keep static and media separated and ensure the web server treats media as untrusted. ([Django Project][3])
---
### DJANGO-REDIRECT-001: Prevent open redirects (`next`, `return_to`, `redirect`)
Severity: Medium (High when combined with auth flows)
Required:
* MUST validate redirect targets derived from untrusted input (e.g., `next`, `return_to`).
* SHOULD restrict to same-site relative paths or allowlisted hosts/schemes.
* SHOULD use Django’s safe URL helpers (e.g., `django.utils.http.url_has_allowed_host_and_scheme`) rather than custom parsing.
Insecure patterns:
* `return redirect(request.GET.get("next"))` with no validation.
* Redirect allowlist implemented with naive string checks.
Detection hints:
* Search for `redirect(` and track origin of the target.
* Search for parameters named `next`, `return_to`, `redirect`, `url`.
Fix:
* Validate with allowlists and default to a safe internal path if validation fails.
* Ensure host validation via `ALLOWED_HOSTS` remains strict (see DJANGO-HOST-001). ([Django Project][3])
---
### DJANGO-HEADERS-001: Enable essential security headers (SecurityMiddleware + clickjacking protection)
Severity: Medium to High
Required:
* SHOULD use `django.middleware.security.SecurityMiddleware` and configure it appropriately (production) for:
* `X-Content-Type-Options: nosniff` (Django setting `SECURE_CONTENT_TYPE_NOSNIFF`, default `True`). ([Django Project][3])
* `Referrer-Policy` (Django setting `SECURE_REFERRER_POLICY`, default `'same-origin'`). ([Django Project][3])
* COOP (Django setting `SECURE_CROSS_ORIGIN_OPENER_POLICY`, default `'same-origin'`). ([Django Project][3])
* HTTPS redirects and HSTS as appropriate (see DJANGO-HTTPS-001). ([Django Project][3])
* SHOULD enable clickjacking protection via X-Frame-Options middleware; Django security docs strongly recommend it for sites that don’t need third-party framing. ([Django Project][2])
Insecure patterns:
* Missing SecurityMiddleware.
* Missing clickjacking protection (or disabling it globally) without a clear framing requirement.
* Over-broad framing allowances for sensitive endpoints.
Detection hints:
* Inspect `MIDDLEWARE` for SecurityMiddleware and XFrameOptionsMiddleware.
* Search for per-view disabling of framing/CSRF protections.
Fix:
* Add/enable middleware and configure the settings intentionally. ([Django Project][3])
NOTE:
* Some headers may be set at the edge (CDN/reverse proxy). If not visible in app code, flag as “verify at edge”.
---
### DJANGO-CSP-001: Deploy a Content Security Policy (CSP) as defense-in-depth
Severity: Medium (High for apps rendering untrusted content)
NOTE: It is most important to set the CSP's script-src. All other directives are not as important and can generally be excluded for the ease of development.
Required:
* SHOULD deploy a CSP to mitigate XSS and content injection classes; Django’s security docs recommend CSP and note it is new in Django 6.0. ([Django Project][2])
* MUST understand CSP limitations:
* Avoid excluding routes from CSP coverage; Django warns that an unprotected page can undermine protected pages due to same-origin policy. ([Django Project][2])
* MAY start with `SECURE_CSP_REPORT_ONLY` to iterate safely (Django provides report-only support). ([Django Project][3])
Insecure patterns:
* No CSP on apps that render user-controlled content.
* CSP excludes “just a couple pages” (weakens overall protection), especially pages with any injection surface. ([Django Project][2])
* CSP uses overly permissive directives (e.g., widespread `unsafe-inline`) without justification.
Detection hints:
* Search `SECURE_CSP`, `SECURE_CSP_REPORT_ONLY`, and CSP middleware configuration.
* Inspect reverse proxy/CDN config for CSP headers.
Fix:
* Implement a realistic CSP, ideally report-only first, then enforce. ([Django Project][3])
---
### DJANGO-AUTH-001: Password storage must use Django’s secure hashers; password policy must be configured
Severity: High
Required:
* MUST use Django’s built-in password hashing (never store plaintext or reversible encrypted passwords).
* SHOULD prefer modern hashers and keep defaults updated; Django documents `PASSWORD_HASHERS` and includes modern options (Argon2, bcrypt, scrypt, PBKDF2 variants). ([Django Project][3])
* SHOULD configure `AUTH_PASSWORD_VALIDATORS` (default is empty) for production password policy. ([Django Project][3])
Insecure patterns:
* Custom password storage or hashing.
* Plaintext passwords stored in DB fields.
* No password validation on consumer-facing apps.
Detection hints:
* Search for `.set_password(` usage vs manual hashing.
* Inspect settings for `PASSWORD_HASHERS` and `AUTH_PASSWORD_VALIDATORS`. ([Django Project][3])
Fix:
* Use Django auth user model APIs.
* Enable password validators appropriate to the product’s risk profile. ([Django Project][3])
---
### DJANGO-AUTHZ-001: Authorization must be explicit and consistent
Severity: High
Required:
* MUST enforce authorization checks on every privileged action (view, modify, admin-like operations).
* MUST NOT rely on UI-only restrictions (e.g., hiding buttons) without server-side permission checks.
* SHOULD use Django’s permissions/groups and per-object authorization patterns where applicable.
Insecure patterns:
* Views that assume “user is logged in” implies “user may do action”.
* Missing authorization checks on update/delete endpoints.
Detection hints:
* Enumerate views that modify state; ensure they validate ownership/permission.
* Look for use of only `is_authenticated` or only `is_staff` without checking object-level access.
Fix:
* Add explicit permission checks and tests for unauthorized access.
---
### DJANGO-ADMIN-001: Django admin must be treated as a high-value target
Severity: High
Required:
* MUST ensure admin is protected by strong authentication and HTTPS-only transport (see DJANGO-HTTPS-001). ([Django Project][1])
* SHOULD restrict admin exposure (network allowlists, VPN, SSO, or additional authentication controls) when possible.
* SHOULD audit installed admin extensions and third-party apps for XSS/CSRF exposure.
Insecure patterns:
* Admin exposed to the internet with weak authentication.
* Admin served over HTTP.
Detection hints:
* Search `urlpatterns` for `admin.site.urls`.
* Check deployment config for IP allowlisting or auth gateways.
Fix:
* Add network controls and enforce HTTPS.
---
### DJANGO-LOG-001: Logging and error reporting must not leak secrets
Severity: Medium to High
Required:
* MUST NOT log secrets (including `SECRET_KEY`, session cookies, auth headers, password reset tokens).
* MUST configure production logging deliberately; Django’s deployment checklist explicitly calls out reviewing logging before production. ([Django Project][1])
* MUST ensure `DEBUG=False` in production so exceptions aren’t rendered with sensitive context. ([Django Project][1])
Insecure patterns:
* Logging full request headers or cookies in production.
* Printing settings dictionaries.
* Debug error pages.
Detection hints:
* Inspect `LOGGING` config; search for middleware that logs request headers/cookies.
* Grep for `print(settings` / `logging.info(request.META)` patterns.
Fix:
* Redact sensitive values; log IDs not secrets.
* Use structured logging and a safe error monitoring tool. ([Django Project][1])
---
### DJANGO-SUPPLY-001: Dependency and patch hygiene (Django + security-critical deps)
Severity: Medium (High if known vulnerable versions)
Required:
* SHOULD pin and regularly update Django and security-critical dependencies.
* MUST respond to Django security releases promptly.
Detection hints:
* Check `requirements.txt`, lockfiles, build images.
* Identify Django version; compare against latest supported release (Django’s download page publishes current stable and supported branches). ([Django Project][9])
Fix:
* Upgrade to patched versions; add regression tests for previously vulnerable classes.
---
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
* Deployment/dev server:
* `manage.py runserver`, `runserver 0.0.0.0`, `--insecure` ([Django Project][1])
* Debug / settings:
* `DEBUG = True` ([Django Project][1])
* `SECRET_KEY =`, `SECRET_KEY_FALLBACKS` ([Django Project][1])
* Host validation:
* `ALLOWED_HOSTS = ['*']` ([Django Project][3])
* HTTPS and proxy:
* `SECURE_SSL_REDIRECT`, `SECURE_HSTS_SECONDS`, `SECURE_PROXY_SSL_HEADER` ([Django Project][3])
* Cookies / sessions:
* `SESSION_COOKIE_SECURE`, `SESSION_COOKIE_HTTPONLY`, `SESSION_COOKIE_SAMESITE` ([Django Project][3])
* `CSRF_COOKIE_SECURE`, `CSRF_COOKIE_HTTPONLY`, `CSRF_COOKIE_SAMESITE` ([Django Project][3])
* CSRF bypasses:
* `csrf_exempt`, missing `CsrfViewMiddleware`, POST forms without `{% csrf_token %}` ([Django Project][4])
* XSS:
* `|safe`, `autoescape off`, `mark_safe(`, HTML string concatenation ([Django Project][5])
* SQL injection:
* `.raw(`, `.extra(`, `RawSQL(`, `cursor.execute(` with formatted SQL strings ([Django Project][7])
* User uploads / media:
* `request.FILES`, `MEDIA_ROOT`, `MEDIA_URL`, serving media inline; `MEDIA_ROOT == STATIC_ROOT` ([Django Project][1])
* Redirects:
* `redirect(request.GET.get("next"))` patterns; missing allowlist validation
* Security headers and CSP:
* Missing `SecurityMiddleware`, missing X-Frame-Options protection, missing `SECURE_CSP` adoption (where appropriate) ([Django Project][2])
Always try to confirm:
* data origin (untrusted vs trusted)
* sink type (template/SQL/subprocess/files/redirect/http)
* protective controls present (middleware, validation, allowlists, authz checks)
* whether security headers/controls are set in-app vs at the edge
---
## 6) Sources (accessed 2026-01-27)
Primary Django documentation:
```text
- Django Downloads (current stable & supported branches): https://www.djangoproject.com/download/
- Django 6.0 Release Notes: https://docs.djangoproject.com/en/6.0/releases/6.0/
- Django: Deployment checklist (incl. check --deploy, runserver warning, HTTPS/cookies guidance): https://docs.djangoproject.com/en/6.0/howto/deployment/checklist/
- Django: Settings reference (SecurityMiddleware settings, cookies, SECRET_KEY_FALLBACKS, CSP settings): https://docs.djangoproject.com/en/6.0/ref/settings/
- Django: Security in Django (XSS/CSRF/SQLi/clickjacking/HTTPS/host header validation/uploads/CSP): https://docs.djangoproject.com/en/6.0/topics/security/
- Django: CSRF how-to (middleware, csrf_token usage, AJAX header patterns, csrf_exempt cautions): https://docs.djangoproject.com/en/6.0/howto/csrf/
- Django: Performing raw SQL queries (parameterization guidance): https://docs.djangoproject.com/en/6.0/topics/db/sql/
- Django: QuerySet API reference (extra() cautions; “do not quote placeholders” guidance): https://docs.djangoproject.com/en/6.0/ref/models/querysets/
- Django: Template built-ins (autoescape tag): https://docs.djangoproject.com/en/6.0/ref/templates/builtins/
- Django: Template language reference (turning off autoescape & risks): https://docs.djangoproject.com/en/6.0/ref/templates/language/
- Django: Utilities reference (e.g., format_html): https://docs.djangoproject.com/en/6.0/ref/utils/
```
OWASP:
```text
- OWASP Cheat Sheet Series: Django Security Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Django_Security_Cheat_Sheet.html
```
[1]: https://docs.djangoproject.com/en/6.0/howto/deployment/checklist/ "https://docs.djangoproject.com/en/6.0/howto/deployment/checklist/"
[2]: https://docs.djangoproject.com/en/6.0/topics/security/ "Security in Django | Django documentation | Django"
[3]: https://docs.djangoproject.com/en/6.0/ref/settings/ "Settings | Django documentation | Django"
[4]: https://docs.djangoproject.com/en/6.0/howto/csrf/ "How to use Django’s CSRF protection | Django documentation | Django"
[5]: https://docs.djangoproject.com/en/6.0/ref/templates/builtins/ "https://docs.djangoproject.com/en/6.0/ref/templates/builtins/"
[6]: https://docs.djangoproject.com/en/6.0/ref/utils/ "https://docs.djangoproject.com/en/6.0/ref/utils/"
[7]: https://docs.djangoproject.com/en/6.0/topics/db/sql/ "https://docs.djangoproject.com/en/6.0/topics/db/sql/"
[8]: https://docs.djangoproject.com/en/6.0/ref/models/querysets/ "https://docs.djangoproject.com/en/6.0/ref/models/querysets/"
[9]: https://www.djangoproject.com/download/ "Download Django | Django"
.blackbox/skills/security-best-practices/references/python-fastapi-web-server-security.md
+1036
View File
File diff suppressed because it is too large Load Diff
.blackbox/skills/security-best-practices/references/python-flask-web-server-security.md
+705
View File
@@ -0,0 +1,705 @@
# Flask (Python) Web Security Spec (Flask 3.1.x, Python 3.x)
This document is designed as a **security spec** that supports:
1) **Secure-by-default code generation** for new Flask code.
2) **Security review / vulnerability hunting** in existing Flask code (passive “notice issues while working” and active “scan the repo and report findings”).
It is intentionally written as a set of **normative requirements** (“MUST/SHOULD/MAY”) plus **audit rules** (what bad patterns look like, how to detect them, and how to fix/mitigate them).
--------------------------------------------------------------------
## 0) Safety, boundaries, and anti-abuse constraints (MUST FOLLOW)
- MUST NOT request, output, log, or commit secrets (API keys, passwords, private keys, session cookies, SECRET_KEY).
- MUST NOT “fix” security by disabling protections (e.g., turning off CSRF, relaxing CORS, disabling escaping, disabling auth checks).
- MUST provide **evidence-based findings** during audits: cite file paths, code snippets, and configuration values that justify the claim.
- MUST treat uncertainty honestly: if a protection might exist in infrastructure (reverse proxy, WAF, CDN), report it as “not visible in app code; verify at runtime/config”.
--------------------------------------------------------------------
## 1) Operating modes
### 1.1 Generation mode (default)
When asked to write new Flask code or modify existing code:
- MUST follow every **MUST** requirement in this spec.
- SHOULD follow every **SHOULD** requirement unless the user explicitly says otherwise.
- MUST prefer safe-by-default APIs and proven libraries over custom security code.
- MUST avoid introducing new risky sinks (template rendering from strings, shell execution, dynamic imports, unsafe redirects, serving user files as HTML, etc.).
### 1.2 Passive review mode (always on while editing)
While working anywhere in a Flask repo (even if the user did not ask for a security scan):
- MUST “notice” violations of this spec in touched/nearby code.
- SHOULD mention issues as they come up, with a brief explanation + safe fix.
### 1.3 Active audit mode (explicit scan request)
When the user asks to “scan”, “audit”, or “hunt for vulns”:
- MUST systematically search the codebase for violations of this spec.
- MUST output findings in a structured format (see §2.3).
Recommended audit order:
1) App entrypoints / deployment scripts / Dockerfiles / Procfiles.
2) Flask configuration and environment handling.
3) Auth + sessions + cookies.
4) CSRF protections and state-changing routes.
5) Template rendering and XSS/SSTI.
6) File handling (uploads + downloads) and path traversal.
7) Injection classes (SQL, command execution, unsafe deserialization).
8) Outbound requests (SSRF).
9) Redirect handling (open redirects).
10) CORS and security headers.
--------------------------------------------------------------------
## 2) Definitions and review guidance
### 2.1 Untrusted input (treat as attacker-controlled unless proven otherwise)
Examples include:
- `request.args`, `request.form`, `request.values`
- `request.get_json()`, `request.json`, `request.data`
- `request.headers`, `request.cookies`
- URL path parameters (e.g., `/user/<id>`)
- Any data from external systems (webhooks, third-party APIs, message queues)
- Any persisted user content (DB rows) that originated from users
### 2.2 State-changing request
A request is state-changing if it can create/update/delete data, change auth/session state, trigger side effects (purchase, email send, webhook send), or initiate privileged actions.
### 2.3 Required audit finding format
For each issue found, output:
- Rule ID:
- Severity: Critical / High / Medium / Low
- Location: file path + function/route name + line(s)
- Evidence: the exact code/config snippet
- Impact: what could go wrong, who can exploit it
- Fix: safe change (prefer minimal diff)
- Mitigation: defense-in-depth if immediate fix is hard
- False positive notes: what to verify if uncertain
--------------------------------------------------------------------
## 3) Secure baseline: minimum production configuration (MUST in production)
This is the smallest “production baseline” that prevents common Flask misconfigurations.
### 3.1 App initialization pattern (SHOULD)
SHOULD use an app factory and environment-based config so production config is not hard-coded.
Example skeleton (illustrative; adjust to your project):
- Load config from environment / secret store.
- Fail closed if critical settings are missing in production.
Key baseline config targets:
- `SECRET_KEY` set and not committed
- `SESSION_COOKIE_SECURE=True` (when HTTPS) IMPORTANT NOTE: Only set `Secure` in production environment when TLS is configured. When running in a local dev environment over HTTP, do not set `Secure` property on cookies. You should do this conditionally based on if the app is running in production mode. You should also include a property like `SESSION_COOKIE_SECURE` which can be used to disable `Secure` cookies when testing over HTTP.
- `SESSION_COOKIE_HTTPONLY=True`
- `SESSION_COOKIE_SAMESITE='Lax'` (or `'Strict'` if compatible)
- `TRUSTED_HOSTS` set in production
- Security headers set (CSP, etc.) either in app or at the edge
--------------------------------------------------------------------
## 4) Rules (generation + audit)
Each rule contains: required practice, insecure patterns, detection hints, and remediation.
### FLASK-DEPLOY-001: Do not use Flask’s development server in production
Severity: High (if production)
Required:
- MUST NOT deploy the built-in development server as the production server.
- MUST run behind a production-grade WSGI server or managed platform (such as gunicorn)
Insecure patterns:
- `app.run(...)` in a production entrypoint.
- Deployment docs/scripts that use `flask run` in production.
Detection hints:
- Search for `app.run(`, `flask run`, `--debug`, `FLASK_DEBUG`, `FLASK_ENV=development`.
- Check Docker CMD/ENTRYPOINT, Procfile, systemd units, shell scripts.
Fix:
- Use a production WSGI server (and keep Flask as the app object).
- Ensure the dev server is only used for local development.
Note:
- These are often used in dev mode or local testing. This is allowed. Only flag if it is clear that it is being used as the production entrypoint
---
### FLASK-DEPLOY-002: Debug mode MUST be disabled in production
Severity: Critical
Required:
- MUST NOT enable debug mode in production.
- MUST treat the interactive debugger as equivalent to remote code execution if exposed.
Insecure patterns:
- `app.run(debug=True)`
- `flask run --debug` in production.
- `DEBUG=True` via env/config in production.
Detection hints:
- Look for `debug=True`, `FLASK_DEBUG=1`, `DEBUG = True`, `app.debug = True`.
- Look for `TRAP_HTTP_EXCEPTIONS`/debugger settings enabled in non-test contexts.
Fix:
- Ensure debug is only enabled in local dev/test.
- Prefer environment-based toggles and safe defaults.
Note:
- These are often used in dev mode or local testing. This is allowed. Only flag if it is clear that it is being used as the production entrypoint
---
### FLASK-CONFIG-001: SECRET_KEY must be strong, secret, and rotated safely
Severity: High (Critical if missing in production with sessions or signing)
Required:
- MUST set a strong random `SECRET_KEY` in production.
- MUST keep `SECRET_KEY` out of source control and out of logs.
- MAY rotate keys periodically; MAY use `SECRET_KEY_FALLBACKS` to support rotation without instantly invalidating existing sessions, then remove old keys after the rotation window. This likely is not needed for smaller applications but is good practice for larger applications. As this may complicate deployment, suggest that it be implemented rather than implementing it by default.
Insecure patterns:
- Missing `SECRET_KEY` in production.
- Hard-coded `SECRET_KEY` in repo (including test keys accidentally used in prod).
- Logging or printing `SECRET_KEY`.
Detection hints:
- Search for `SECRET_KEY =`, `app.secret_key =`, `SECRET_KEY_FALLBACKS =`.
- Check `.env` files committed to repo.
- Check config modules for constants.
Fix:
- Load from secret manager or environment variable.
- Add a rotation process:
- Set new `SECRET_KEY`
- Keep old key(s) temporarily in `SECRET_KEY_FALLBACKS`
- Remove old key(s) after the safe window.
Notes:
- If the application uses Flask sessions (cookie-based by default), `SECRET_KEY` is directly security-critical.
---
### FLASK-SESS-001: Session cookies must use secure attributes in production
Severity: Medium
Required (production, HTTPS):
- MUST set `SESSION_COOKIE_SECURE=True` (cookies only over HTTPS). NOTE: Only set `Secure` in production environment when TLS is configured. When running in a local dev environment over HTTP, do not set `Secure` property on cookies. You should do this conditionally based on if the app is running in production mode. You should also include a property like `SESSION_COOKIE_SECURE` which can be used to disable `Secure` cookies when testing over HTTP.
- MUST ensure `SESSION_COOKIE_HTTPONLY=True` (protect from JS access).
- SHOULD set `SESSION_COOKIE_SAMESITE='Lax'` (recommended) or `'Strict'` if compatible with UX.
- SHOULD keep `SESSION_COOKIE_DOMAIN=None` unless you explicitly need subdomain-wide cookies.
- If you need embedded/iframe third-party usage, MAY consider `SESSION_COOKIE_PARTITIONED=True` (requires HTTPS).
Insecure patterns:
- `SESSION_COOKIE_SECURE=False` in production.
- `SESSION_COOKIE_HTTPONLY=False`.
- `SESSION_COOKIE_SAMESITE=None` with cookie-authenticated state-changing endpoints (higher CSRF risk).
Detection hints:
- Inspect `app.config.update(...)` blocks and config classes.
- Look for `set_cookie(..., secure=..., httponly=..., samesite=...)` usage on non-session cookies too.
Fix:
- Set these config values explicitly in production config.
Notes:
- SameSite is defense-in-depth; do not treat it as a full replacement for CSRF tokens.
---
### FLASK-SESS-002: Sessions must be bounded and resistant to fixation/replay
Severity: Medium
Required:
- SHOULD set a bounded session lifetime appropriate to the app.
- SHOULD set `session.permanent = True` only when you intend persistent sessions, and set `PERMANENT_SESSION_LIFETIME` to a justified value.
- SHOULD clear the session on login and privilege changes to reduce session fixation risk.
- MUST NOT store sensitive secrets in the default Flask session cookie. The default session is signed, not encrypted.
Insecure patterns:
- Extremely long or unlimited lifetimes for privileged sessions.
- No session clearing on login.
- Storing secrets (passwords, access tokens, PII) directly in `session[...]` when using default cookie sessions.
Detection hints:
- Search for `PERMANENT_SESSION_LIFETIME`, `session.permanent`, `session[...] =`.
- Identify whether server-side session storage is used; if not, assume default cookie sessions.
Fix:
- Set appropriate lifetimes.
- Clear/rotate session on login.
- Store sensitive data server-side; store only identifiers in the session cookie.
---
### FLASK-CSRF-001: State-changing requests using cookie auth MUST be CSRF-protected
Severity: High
- IMPORTANT NOTE: If cookies are not being used for auth (ie auth is via Authentication header or other passed token), then there is no CSRF risk.
Required:
- MUST protect all state-changing endpoints (POST/PUT/PATCH/DELETE) that rely on cookies for authentication.
- MAY use a well-tested CSRF library/integration (form framework or middleware) rather than rolling your own.
- MAY use additional defenses (Origin/Referer checking, SameSite cookies, Fetch Metadata headers, custom headers for AJAX/API), but tokens remain the primary defense for cookie-authenticated apps.
If tokens are impractical, or for small applications:
* MUST at a minimum require a custom header to be set and set the session cookie SESSION_COOKIE_SAMESITE=lax, as this is the strongest method besides requiring a form token, and may be much easier to implement.
Insecure patterns:
- Cookie-authenticated endpoints that change state with no CSRF protection.
- Using GET for state-changing actions (amplifies CSRF risk).
Detection hints:
- Enumerate routes with methods other than GET and identify auth mechanism.
- Look for CSRF integrations (e.g., Flask-WTF, global CSRF middleware). If absent, treat as suspicious.
- Check JSON API endpoints too, not only HTML forms.
Fix:
- Add CSRF protection to all state-changing requests.
- If the app is a pure API and uses Authorization headers (bearer tokens) rather than cookies, document that choice and ensure cookies aren’t used for auth. If cookies are not used for auth, there is no CSRF risk.
Notes:
- XSS can defeat CSRF protections; CSRF defenses do not replace XSS prevention.
---
### FLASK-XSS-001: Prevent reflected/stored XSS in templates and HTML generation
Severity: High
Required:
- MUST rely on Jinja auto-escaping for HTML templates.
- MUST NOT mark untrusted content as safe:
- Avoid `Markup(...)` on user data.
- Avoid Jinja `|safe` on user-controlled content.
- MUST quote HTML attributes containing Jinja expressions (`value="{{ x }}"` not `value={{ x }}`).
- MUST NOT serve uploaded HTML as active HTML; serve as download (`Content-Disposition: attachment`) or transform to a safe format. Note: This is only relevant if it is possible to upload document content such as html, js, css, etc. If it purely is image files, there is no concern.
- SHOULD deploy a Content Security Policy (CSP) to mitigate XSS classes (including `javascript:` in `href`).
Insecure patterns:
- `Markup(request.args.get(...))`
- Template filters: `{{ user_html|safe }}`
- Unquoted attributes in templates
- Serving user-uploaded content directly with `text/html` or inline rendering
Detection hints:
- Search for `Markup(` and investigate origin of the data.
- Search template files for `|safe`, `|tojson` misuse, and unquoted attributes.
- Review file-serving routes that might return user uploads without `as_attachment=True`. Note: This is only relevant if it is possible to upload document content such as html, js, css, etc. If it purely is image files, there is no concern.
Fix:
- Remove unsafe marking; sanitize only when strictly necessary using a trusted HTML sanitizer.
- Always quote attributes.
- Add CSP and reduce inline scripts.
---
### FLASK-SSTI-001: Never render untrusted templates (Server-Side Template Injection)
Severity: Critical
Required:
- MUST NOT render templates that contain user-controlled template syntax.
- MUST treat `render_template_string` and `Environment.from_string(...).render(...)` as dangerous if the template string is influenced by untrusted input.
- MUST NOT use use `.format()` on user controlled strings
- If untrusted templates are absolutely required, treat it as a special high-risk design:
- MUST use a sandboxed templating approach and restrict capabilities.
- MUST keep Jinja updated and assume sandbox escapes are possible; isolate further.
Insecure patterns:
- `render_template_string(request.args["tmpl"], ...)`
- Storing user templates in DB and rendering them with the normal Jinja environment.
- `request.args["tmpl"].format(...)`
Detection hints:
- Grep for `render_template_string`, `from_string`, `.render(` with dynamic strings.
- Trace the origin of the template string (DB, request, uploads, admin panels).
Fix:
- Replace with safe templating alternatives that do not evaluate code (e.g., string.Template, str.replace).
- If templates must be user-defined, use a sandbox plus strict allowlists and heavy isolation.
---
### FLASK-HEADERS-001: Set essential security headers (in app or at the edge)
Severity: Medium
Required (typical web app):
- SHOULD set:
- CSP (`Content-Security-Policy`)
- `X-Content-Type-Options: nosniff`
- Clickjacking protection (`X-Frame-Options: SAMEORIGIN` and/or CSP `frame-ancestors`) (there may be cases where the user wants to iframe their site elsewhere. If that is the case, work with them to safely allow it)
- SHOULD consider additional hardening headers depending on app (Referrer-Policy, Permissions-Policy).
- MUST ensure cookies are set with secure attributes (see FLASK-SESS-001).
NOTE: Security headers may be set via a proxy or other cloud provider. Check to see if there is evidence of that.
Insecure patterns:
- No security headers anywhere (app or edge).
- CSP missing on apps that display untrusted content.
Detection hints:
- Search for `after_request` hooks, Flask-Talisman usage, reverse proxy config.
- If not visible in app code, flag as “verify at edge”.
Fix:
- Set headers centrally (middleware / after_request) or via reverse proxy/CDN.
- Keep CSP realistic and compatible; avoid `unsafe-inline` where possible.
---
### FLASK-LIMITS-001: Request size and form parsing limits MUST be set appropriately
Severity: Low (Medium if file uploads / large bodies are possible)
Required:
- SHOULD set and justify:
- `MAX_CONTENT_LENGTH` (global maximum request bytes)
- `MAX_FORM_MEMORY_SIZE` (max per non-file form field in multipart)
- `MAX_FORM_PARTS` (max number of multipart fields)
- MUST enforce additional limits at the reverse proxy / WSGI / platform level where possible.
Insecure patterns:
- Unlimited request body sizes when handling uploads or user content.
- Accepting arbitrarily large multipart forms or many fields.
Detection hints:
- Inspect Flask config for these keys.
- Inspect upload routes and APIs that accept large JSON.
Fix:
- Set conservative defaults, override per-route only when needed.
- Ensure large uploads use dedicated upload mechanisms.
---
### FLASK-HOST-001: Host header must be validated in production
Severity: Low (depends on app’s use of external URLs)
Required:
- MUST set `TRUSTED_HOSTS` in production to restrict accepted Host values.
- MUST NOT rely on `SERVER_NAME` as a host restriction mechanism.
Insecure patterns:
- `TRUSTED_HOSTS` unset in production.
- Code that generates external URLs for emails/password resets without host validation.
Detection hints:
- Find `TRUSTED_HOSTS` config usage.
- Find `url_for(..., _external=True)` and check how host is determined.
Fix:
- Set `TRUSTED_HOSTS` to your expected domains (and required subdomains).
- Ensure external URL generation uses trusted host/scheme.
---
### FLASK-PROXY-001: Reverse proxy trust must be configured correctly
Severity: Medium (High if relying on IPs for auth)
Required:
- If behind a reverse proxy, MUST configure Flask/Werkzeug to trust forwarded headers only from the intended proxy.
- MUST NOT blindly trust `X-Forwarded-*` headers from the open internet.
Insecure patterns:
- `ProxyFix` applied with overly broad trust settings, or applied without understanding how many proxies are in front.
- Relying on forwarded headers for scheme/host without validation.
Detection hints:
- Search for `ProxyFix`.
- Search for usage of `request.remote_addr`, `request.scheme`, `request.host` in security-sensitive logic.
Fix:
- Configure `ProxyFix` (or platform-specific settings) with correct hop counts.
- Keep `TRUSTED_HOSTS` in place even behind proxies.
---
### FLASK-PATH-001: Prevent path traversal and unsafe file serving
Severity: High
Required:
- MUST NOT pass user-controlled file paths to `send_file` or to direct file I/O.
- MUST use safe file serving patterns:
- `send_from_directory` for user-specified paths under a trusted base directory
- `safe_join` for joining a trusted base directory with untrusted path components
- `secure_filename` for uploaded filenames (and still generate your own unique storage name)
- MUST ensure user uploads are not served as executable/active content (especially HTML).
- SHOULD in general use `safe_join` over `os.path.join` for almost any filesystem path computations.
Insecure patterns:
- `send_file(request.args["path"])`
- `open(os.path.join(base_dir, user_path))` where `user_path` is untrusted
- Serving uploads from within a static web root without restrictions
Detection hints:
- Search for `send_file(`, `open(`, `os.path.join(`, `pathlib.Path(...)/...` in file routes.
- Identify where filenames come from (request args, DB, headers).
Fix:
- Serve only from a non-user-controlled directory base.
- Store uploads outside static roots; serve through controlled routes.
- Always validate and normalize file identifiers.
Note: `safe_join` is imported from `werkzeug.security`
---
### FLASK-UPLOAD-001: File uploads must be validated, stored safely, and served safely
Severity: High
Required:
- MUST enforce upload size limits (app + edge).
- MUST validate file type using allowlists and content checks (not only extension).
- MUST store uploads outside executable/static roots when possible.
- SHOULD generate server-side filenames (random IDs) and avoid trusting original names.
- MUST serve potentially active formats safely (download attachment) unless explicitly intended.
Insecure patterns:
- Accepting arbitrary file types and serving them back inline.
- Using user-supplied filename as storage path.
- Missing size/type validation.
Detection hints:
- Look for `request.files[...]` handlers.
- Check for `secure_filename` usage (and whether it’s combined with uniqueness).
- Check where files are stored and how they are served.
Fix:
- Implement allowlist validation + safe storage + safe serving.
- Add scanning / quarantine if applicable.
---
### FLASK-INJECT-001: Prevent SQL injection (use parameterized queries / ORM)
Severity: High
Required:
- MUST use parameterized queries or an ORM that parameterizes under the hood.
- MUST NOT build SQL by string concatenation / f-strings with untrusted input.
Insecure patterns:
- `f"SELECT ... WHERE id={request.args['id']}"`
- `"... WHERE name = '%s'" % user_input`
Detection hints:
- Grep for `SELECT`, `INSERT`, `UPDATE`, `DELETE` strings in Python code.
- Track untrusted data into DB execute calls.
Fix:
- Replace with parameterized queries or ORM query APIs.
- Validate types (e.g., int IDs) before querying.
---
### FLASK-INJECT-002: Prevent OS command injection
Severity: Critical to High (depends on exposure)
Required:
- MUST avoid executing shell commands with untrusted input.
- If subprocess is necessary:
- MUST pass args as a list (not a string)
- MUST NOT use `shell=True` with attacker-influenced strings
- SHOULD use strict allowlists for any variable component
- If possible, use pure python or a python library rather than using a subprocess or system command
- Do not assume that arguments to commands will be inherently safe even in `shell=False`. Commands may incorrectly process these arguments as command line flags or other trusted values.
Insecure patterns:
- `os.system(user_input)`
- `subprocess.run(f"cmd {user}", shell=True)`
- Passing user strings into `bash -c`, `sh -c`, PowerShell, etc.
Detection hints:
- Search for `os.system`, `subprocess`, `Popen`, `shell=True`.
- Trace data from request/DB into these calls.
Fix:
- Use library APIs instead of shell commands.
- If unavoidable, hard-code the command and allowlist validated parameters. If supported by the subcommand, try to keep user values after `--` to prevent them being processed as command line flags.
---
### FLASK-SSRF-001: Prevent server-side request forgery (SSRF) in outbound HTTP
Severity: Medium
- Note: For small stand alone projects this is less important. It is most important when deploying into an LAN or with other services listening on the same server.
Required:
- MUST treat outbound requests to user-provided URLs as high risk.
- SHOULD validate and restrict destinations (allowlist hosts/domains) for any user-influenced URL fetch.
- SHOULD block access to:
- localhost / private IP ranges / link-local addresses
- cloud metadata endpoints
- MUST NOT allow non http/https protocols (ie file: etc)
- SHOULD set timeouts and restrict redirects.
Insecure patterns:
- `requests.get(request.args["url"])`
- Webhooks/preview/fetch endpoints that accept arbitrary URLs.
Detection hints:
- Search for `requests.get/post`, `httpx`, `urllib`, `aiohttp` usage with untrusted URL sources.
- Identify URL fetch features (preview, import, webhook tester).
Fix:
- Ensure URLs are http or https (disallow file: or other protocols)
- Enforce allowlists and network egress controls.
- Add strict parsing and IP resolution checks; set timeouts; disable redirects if not needed.
---
### FLASK-REDIRECT-001: Prevent open redirects
Severity: Low
Required:
- MUST validate redirect targets derived from untrusted input (e.g., `next`, `redirect`, `return_to`).
- SHOULD use allowlists of internal paths or known domains.
- SHOULD prefer redirecting only to same-site relative paths.
Insecure patterns:
- `redirect(request.args.get("next"))` with no validation.
Detection hints:
- Search for `redirect(` and examine where `location` comes from.
Fix:
- Only allow relative paths or allowlisted domains.
- Fall back to a safe default if validation fails.
---
### FLASK-HTTP-001: Use HTTP methods safely; do not change state via GET; avoid secrets in URLs
Severity: Medium
Required:
- MUST NOT perform state-changing actions over GET.
- MUST NOT put secrets in URLs (query strings are commonly logged and leaked via referrers).
- SHOULD require POST/PUT/PATCH/DELETE for state change and apply CSRF protections when cookie-authenticated.
Insecure patterns:
- `/delete?id=...` implemented as GET
- Password reset tokens or API keys in query params
Detection hints:
- Enumerate GET routes and inspect whether they mutate state.
- Look for URL parameters named `token`, `key`, `secret`, `password`, etc.
Fix:
- Move state changes to non-GET methods.
- Move sensitive values to secure channels (POST bodies, headers) and protect them.
---
### FLASK-CORS-001: CORS must be explicit and least-privilege
Severity: Medium (High if misconfigured with credentials)
Required:
- If CORS is not needed, MUST keep it disabled.
- If CORS is needed:
- MUST allowlist trusted origins (do not reflect arbitrary origins).
- MUST be careful with credentialed requests; do not combine broad origins with cookies.
- SHOULD restrict allowed methods and headers.
Insecure patterns:
- `Access-Control-Allow-Origin: *` paired with credentialed cookies or overly broad access.
- Reflecting `Origin` without validation.
- `flask_cors.CORS(app)` with permissive defaults.
Detection hints:
- Search for `flask_cors`, `CORS(`, `Access-Control-Allow-Origin`.
- Check for `supports_credentials=True` and wildcard origins.
Fix:
- Use a strict origin allowlist and minimal methods/headers.
- Ensure cookie-authenticated endpoints are not exposed cross-origin unless necessary.
---
### FLASK-SUPPLY-001: Dependency and patch hygiene (focus on security-relevant deps)
Severity: Low
Required:
- SHOULD pin and regularly update security-critical dependencies (Flask, Werkzeug, Jinja2, itsdangerous).
- MUST respond to known security advisories promptly.
Audit focus example:
- If running on Windows and using file serving with untrusted paths, ensure Werkzeug’s `safe_join` behavior is not vulnerable to Windows device-name edge cases.
Detection hints:
- Check `requirements.txt`, lockfiles, and runtime environments.
- Identify where security helpers are used (safe_join, send_from_directory).
Fix:
- Upgrade to patched versions and add regression tests for the impacted behavior.
--------------------------------------------------------------------
## 5) Practical scanning heuristics (how to “hunt”)
When actively scanning, use these high-signal patterns:
- Dev server / debug:
- `app.run(`, `flask run`, `--debug`, `DEBUG=True`, `FLASK_DEBUG`
- Secrets:
- `SECRET_KEY`, `secret_key`, `.env` committed, `print(config)`
- Cookies / sessions:
- `SESSION_COOKIE_SECURE`, `SESSION_COOKIE_HTTPONLY`, `SESSION_COOKIE_SAMESITE`
- `session[...] =` with sensitive values
- CSRF:
- POST/PUT/PATCH/DELETE handlers without CSRF checks in cookie-authenticated apps
- XSS/SSTI:
- `Markup(`, `|safe`, unquoted attributes, `render_template_string`
- Files:
- `send_file(` with user-controlled path; `open(` on user path; `os.path.join` with untrusted
- upload handlers using user filename for path
- Injection:
- SQL strings + string formatting into `.execute(...)`
- `subprocess.*`, `shell=True`, `os.system`
- SSRF:
- `requests.get/post` or `httpx` with URL from request/DB
- Redirect:
- `redirect(request.args.get("next"))`
- CORS:
- `flask_cors.CORS` permissive configs; wildcard origins with credentials
Always try to confirm:
- data origin (untrusted vs trusted)
- sink type (template/SQL/subprocess/files/redirect/http)
- protective controls present (validation, allowlists, middleware)
--------------------------------------------------------------------
## 6) Sources (accessed 2026-01-26)
Primary framework documentation:
- Flask Docs: Deploying to Production — https://flask.palletsprojects.com/en/stable/deploying/
- Flask Docs: Debugging Application Errors — https://flask.palletsprojects.com/en/stable/debugging/
- Flask Docs: Configuration Handling — https://flask.palletsprojects.com/en/stable/config/
- Flask Docs: Security Considerations — https://flask.palletsprojects.com/en/stable/web-security/
- Flask Docs: Tell Flask it is Behind a Proxy — https://flask.palletsprojects.com/en/stable/deploying/proxy_fix/
- Flask API Docs: Sessions — https://flask.palletsprojects.com/en/stable/api/#sessions
Werkzeug documentation & advisories:
- Werkzeug Docs: Utilities (send_file / send_from_directory / safe_join / secure_filename / password hashing) — https://werkzeug.palletsprojects.com/en/stable/utils/
- GitHub Advisory: CVE-2025-66221 (Werkzeug safe_join Windows device names) — https://github.com/advisories/GHSA-hgf8-39gv-g3f2
OWASP Cheat Sheet Series:
- Session Management — https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
- CSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
- XSS Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
- Input Validation — https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
- SQL Injection Prevention — https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html
- Injection Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Injection_Prevention_Cheat_Sheet.html
- OS Command Injection Defense — https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html
- SSRF Prevention — https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html
- File Upload — https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html
- Unvalidated Redirects — https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html
- HTTP Headers — https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html
Template safety references:
- Jinja: Sandbox (rendering untrusted templates) — https://jinja.palletsprojects.com/en/stable/sandbox/
- OWASP WSTG: Testing for Server-Side Template Injection — https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/07-Input_Validation_Testing/18-Testing_for_Server_Side_Template_Injection
- PortSwigger Web Security Academy: Server-side template injection — https://portswigger.net/web-security/server-side-template-injection
HTTP semantics:
- RFC 9110: HTTP Semantics (safe methods) — https://www.rfc-editor.org/rfc/rfc9110
.blackbox/skills/seo/SKILL.md
+114
View File
@@ -0,0 +1,114 @@
---
name: seo
description: Comprehensive SEO analysis for websites and businesses. Audit technical SEO, content quality (E-E-A-T), schema markup, sitemaps, Core Web Vitals with INP, image optimization, and AI search readiness for AI Overviews, ChatGPT, and Perplexity. Use when requests mention SEO, audit, schema, Core Web Vitals, sitemap, technical SEO, content quality, E-E-A-T, GEO, AI crawler access, llms.txt, programmatic SEO, competitor pages, or hreflang.
---
# SEO
Perform comprehensive SEO analysis across SaaS, local services, e-commerce, publishers, agencies, and mixed business models. Run full audits or focused deep-dives, then return prioritized actions with clear severity.
## Command Map
| Command | Action |
|---------|--------|
| `/seo audit <url>` | Run full website audit with parallel workstreams |
| `/seo page <url>` | Run deep single-page analysis |
| `/seo sitemap <url or generate>` | Audit or generate XML sitemap strategy |
| `/seo schema <url>` | Detect, validate, and generate schema |
| `/seo images <url>` | Audit image SEO and media delivery |
| `/seo technical <url>` | Audit crawlability/indexability/infra |
| `/seo content <url>` | Evaluate E-E-A-T and content quality |
| `/seo geo <url>` | Audit AI Overviews and GEO readiness |
| `/seo plan <business-type>` | Produce strategic SEO roadmap |
| `/seo programmatic [url|plan]` | Analyze programmatic SEO viability |
| `/seo competitor-pages [url|generate]` | Build competitor comparison page plan |
| `/seo hreflang [url]` | Audit hreflang and i18n SEO coverage |
## Full Audit Workflow
For `/seo audit <url>`, execute this order:
1. Detect business type from homepage signals.
2. Run six tracks in parallel when possible:
- Technical SEO
- Content quality
- Schema
- Sitemap
- Performance
- Visual/mobile UX
3. Compute unified SEO Health Score.
4. Return findings sorted by priority:
- Critical: fix now
- High: fix within 1 week
- Medium: fix within 1 month
- Low: backlog
5. Provide a concrete action plan with expected impact.
## Business Type Detection
Infer primary business type using homepage and IA signals:
- SaaS: `/pricing`, `/features`, `/integrations`, `/docs`, "free trial", "sign up"
- Local service: address, phone, map embed, service areas, city modifiers
- E-commerce: `/products`, `/collections`, cart flows, Product schema
- Publisher: `/blog`, `/articles`, author pages, publish/update dates
- Agency: `/case-studies`, `/portfolio`, client logos, industry pages
If mixed signals exist, mark "hybrid" and tailor recommendations per page cluster.
## Quality Gates
Apply these non-negotiable rules:
- Warn at 30+ location pages and require at least 60% unique content per page.
- Hard stop at 50+ location pages unless user explicitly justifies scale and differentiation plan.
- Never recommend HowTo schema as an SEO lever.
- Recommend FAQ schema only for government and healthcare websites.
- Use INP for responsiveness; do not use FID in recommendations.
Load `references/quality-gates.md` before auditing large template sets.
## Scoring Model
Use weighted aggregate:
| Category | Weight |
|----------|--------|
| Technical SEO | 25% |
| Content Quality | 25% |
| On-Page SEO | 20% |
| Schema / Structured Data | 10% |
| Performance (CWV) | 10% |
| Images | 5% |
| AI Search Readiness | 5% |
Round final score to nearest integer and explain largest negative contributors.
## Reference Loading Rules
Do not load every reference at startup. Load only what the task needs:
- `references/cwv-thresholds.md`: CWV threshold checks and measurement caveats
- `references/schema-types.md`: supported/deprecated schema and eligibility notes
- `references/eeat-framework.md`: E-E-A-T evaluation rubric
- `references/quality-gates.md`: thin content and scaled-page gating rules
## Sub-Skills and Delegation
Use these capability labels in reports:
1. `seo-audit`
2. `seo-page`
3. `seo-technical`
4. `seo-content`
5. `seo-schema`
6. `seo-images`
7. `seo-sitemap`
8. `seo-geo`
9. `seo-plan`
10. `seo-programmatic`
11. `seo-competitor-pages`
12. `seo-hreflang`
When splitting a full audit, delegate these tracks in parallel:
- `seo-technical`
- `seo-content`
- `seo-schema`
- `seo-sitemap`
- `seo-performance`
- `seo-visual`
.blackbox/skills/seo/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "SEO"
short_description: "Analyze websites for technical and content SEO issues"
default_prompt: "Run a full SEO audit and prioritized action plan for this website"
.blackbox/skills/seo/references/cwv-thresholds.md
+50
View File
@@ -0,0 +1,50 @@
# Core Web Vitals Thresholds (INP-era)
Use field data first (CrUX/RUM), then lab data for diagnosis.
## Primary Metrics
| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| LCP | <= 2.5s | > 2.5s and <= 4.0s | > 4.0s |
| INP | <= 200ms | > 200ms and <= 500ms | > 500ms |
| CLS | <= 0.10 | > 0.10 and <= 0.25 | > 0.25 |
## Supporting Diagnostics
Use these as diagnostic hints, not ranking stand-ins:
| Metric | Suggested Target |
|--------|------------------|
| TTFB | <= 0.8s |
| FCP | <= 1.8s |
| Total Blocking Time (lab) | <= 200ms |
| Main-thread long tasks | < 50ms each where possible |
## Measurement Hierarchy
1. Field data source priority:
- CrUX (origin + URL level if available)
- First-party RUM
2. Lab data source priority:
- PageSpeed Insights lab profile
- Lighthouse (mobile + throttled) for reproducible debugging
## Audit Instructions
1. Compare mobile first, then desktop.
2. Classify each page template by CWV risk:
- Critical: poor in any primary metric on key template
- High: needs improvement on key conversion template
- Medium: issue on secondary templates
3. Map root causes:
- LCP: render-blocking CSS/JS, slow HTML, heavy hero image
- INP: long JS tasks, expensive handlers, third-party script contention
- CLS: unsized media, ad/embed shifts, late DOM injections
4. Propose one quick win and one structural fix per failing metric.
## Rules
- Always use INP. Do not reference FID as a current optimization target.
- Avoid over-claiming from synthetic tests alone.
- If field data is unavailable, clearly label findings as provisional.
.blackbox/skills/seo/references/eeat-framework.md
+73
View File
@@ -0,0 +1,73 @@
# E-E-A-T Evaluation Framework
Use this rubric to evaluate content quality for competitive queries.
## Dimensions
Score each dimension from 0 to 5:
| Dimension | What to Check |
|-----------|---------------|
| Experience | First-hand evidence, practical examples, real usage context |
| Expertise | Subject competence, technical accuracy, depth, specialist language used correctly |
| Authoritativeness | Reputation signals, citations, recognized brand/person entities |
| Trustworthiness | Accuracy, transparency, policy clarity, editorial rigor, safety disclosures |
## Query Stakes Classification
Classify intent before scoring:
- YMYL-high: finance, health, legal, safety
- Commercial-high: high-ticket buying decisions
- Informational-competitive: dense SERP competition with strong entities
- Informational-low: low-risk, basic educational intent
Raise trust requirements for higher-stakes intents.
## Evidence Checklist
Review per template:
1. Authorship clarity:
- named author
- credentials or role
- updated timestamp
2. Source quality:
- primary sources cited
- external corroboration
- quote/context integrity
3. Editorial quality:
- original analysis (not paraphrased commodity text)
- internal consistency across pages
- clear claims with evidence
4. Trust assets:
- about page and editorial policy
- contact and business identity
- privacy and terms links
5. User value:
- intent match
- completeness
- actionable depth
## Risk Flags
Flag as high risk when you find:
- anonymous or credential-free expert claims on high-stakes pages
- copied or near-duplicate boilerplate across key landing pages
- medical/financial/legal recommendations without sourcing
- exaggerated claims without verifiable proof
## Scoring Output Format
Return:
1. Overall content quality score (0-100)
2. Per-dimension scores mapped from rubric
3. Top 3 trust risks
4. Fastest high-impact remediation actions
## Remediation Patterns
- Add expert-reviewed blocks with named reviewers on high-stakes pages.
- Replace generic intros with first-hand evidence and data-backed claims.
- Add citation discipline: primary sources first, then secondary context.
- Standardize author bylines, update dates, and revision ownership.
.blackbox/skills/seo/references/quality-gates.md
+62
View File
@@ -0,0 +1,62 @@
# Content Quality Gates
Use these gates before recommending scale, templates, or programmatic rollout.
## Thin Content Thresholds
Apply minimum effective content targets by page type:
| Page Type | Minimum Body Content | Minimum Unique Content | Notes |
|-----------|----------------------|------------------------|-------|
| Homepage | 500 words | 70% | Differentiate value proposition and audience |
| Service page | 700 words | 70% | Include process, proof, and FAQs |
| Location page | 600 words | 60% | Require city-specific proof and context |
| Product category | 350 words | 65% | Add buyer guidance, not filler |
| Product detail | 250 words | 80% | Unique specs, differentiators, and use cases |
| Blog/article | 900 words | 75% | Include original insights and references |
| Competitor comparison | 1000 words | 80% | Require side-by-side evidence |
If intent is fully satisfied with less copy, allow exception only with strong evidence (high engagement and conversion outcomes).
## Scaled Location Page Rules
- Warning threshold: 30+ location pages.
- Hard stop threshold: 50+ location pages.
- Require at least 60% unique content per location page.
- Require at least 3 localized proof elements per page:
- local testimonials/case studies
- location-specific service details
- local team, office, or coverage details
At hard stop, ask for explicit user justification before proceeding with large-scale rollout.
## Programmatic SEO Gates
Before recommending programmatic generation:
1. Confirm variable set produces real informational differences.
2. Confirm pages can include unique utility (data, tools, comparisons, or local proof).
3. Reject if output would only swap tokens (city/product names) in near-identical copy.
4. Define canonicalization and indexability strategy up front.
## Duplication Risk Bands
| Similarity Between Pages | Risk Level | Action |
|--------------------------|------------|--------|
| < 40% shared text | Low | Proceed |
| 40% to 60% shared text | Medium | Add differentiators before publishing |
| > 60% shared text | High | Block rollout until content model is redesigned |
## Schema Content Policy
- Do not recommend HowTo schema as a growth recommendation.
- Limit FAQ schema recommendations to government and healthcare sites.
- Ensure structured data mirrors visible page content.
## Gate Outcome Labels
Return one of:
- `pass`: Meets thresholds
- `pass_with_risk`: Can ship with documented constraints
- `fail`: Block and redesign content strategy
Always include concrete remediation steps for `pass_with_risk` and `fail`.
.blackbox/skills/seo/references/schema-types.md
+61
View File
@@ -0,0 +1,61 @@
# Schema Type Guidance
Prefer JSON-LD. Validate syntax and eligibility before recommending implementation.
## Recommended by Site Type
| Site Type | Primary Schema | Secondary Schema |
|-----------|----------------|------------------|
| SaaS | `SoftwareApplication`, `Organization` | `Product`, `BreadcrumbList`, `WebSite` |
| Local service | `LocalBusiness` (or subtype), `Organization` | `Service`, `Review`, `BreadcrumbList` |
| E-commerce | `Product`, `Offer`, `AggregateRating` | `Organization`, `BreadcrumbList`, `ItemList` |
| Publisher | `Article`/`NewsArticle`, `Person`, `Organization` | `BreadcrumbList`, `ImageObject` |
| Agency | `Organization`, `Service` | `FAQPage` (restricted use), `BreadcrumbList` |
## Important Eligibility Notes
- Do not recommend `HowTo` as an SEO growth tactic.
- Recommend `FAQPage` only for government and healthcare use cases.
- Keep markup aligned with visible on-page content.
- Prefer one coherent graph over fragmented duplicate blocks.
## Global Baseline Types
Implement these where applicable:
- `Organization` with logo, URL, sameAs
- `WebSite` with `SearchAction` if site search exists
- `BreadcrumbList` on hierarchical pages
## E-commerce Essentials
For product pages, include:
- `name`
- `description`
- `image`
- `sku` or `gtin` when available
- `brand`
- `offers` (`price`, `priceCurrency`, `availability`, `url`)
- `aggregateRating` only when genuine ratings exist
## Publisher Essentials
For article pages, include:
- `headline`
- `datePublished`
- `dateModified`
- `author`
- `publisher`
- `mainEntityOfPage`
- `image`
## Validation Workflow
1. Detect current schema blocks and type coverage.
2. Validate syntax and required fields.
3. Check content parity (structured data must match rendered content).
4. Remove conflicting or duplicate nodes.
5. Prioritize schema by impact:
- Critical: invalid structured data causing parsing failures
- High: missing core schema for primary page type
- Medium: missing enrichment fields
- Low: optional graph enhancements
.blackbox/skills/tdvorak-fullstack/SKILL.md
+43
View File
@@ -0,0 +1,43 @@
---
name: tdvorak-fullstack
description: "Personal default skill for building or extending TDvorak projects as production-grade SaaS or PaaS software. Use when Codex needs to scaffold, architect, refactor, or polish a full-stack product with TDvorak's preferred defaults: SolidJS first with React fallback, Vite, TypeScript, Tailwind, Ark UI or shadcn, Better Auth, Go and Gin APIs, PostgreSQL with sqlc and goose, OpenAPI-generated TypeScript clients, Docker Compose, and premium product-grade UI standards."
---
# TDvorak Fullstack
Use this skill as the default operating profile for TDvorak projects. Optimize for production quality, calm premium UI, predictable architecture, and maintainable delivery speed.
## Workflow
1. Inspect the repository before choosing tools. Reuse established project conventions unless the user explicitly asks to migrate toward these defaults.
2. If the stack is open-ended, default to the architecture in `references/architecture.md`.
3. Before building frontend UI, follow the component selection order in `references/ui-standards.md`.
4. Read only the reference files relevant to the task:
- `references/architecture.md` for stack, backend, auth, API, database, infra, and project layout defaults.
- `references/ui-standards.md` for product polish, component sourcing, spacing, typography, motion - motion.dev, responsiveness, and the visual quality bar.
5. Keep the output production-oriented. Favor small focused modules, generated API types, accessible components, responsive layouts, and Docker-based local runs.
## Non-Negotiables
- Prefer SolidJS for greenfield frontend work. Use React only when the project or dependency constraints make Solid materially worse.
- Prefer Go with Gin for HTTP APIs. Introduce Rust or Python only when justified by task constraints.
- Define API contracts in OpenAPI and generate TypeScript clients and types from the spec. Do not hand-maintain duplicate request or response types.
- Use PostgreSQL, sqlc, and goose for persistence and schema evolution.
- Use Better Auth for authentication when auth is required.
- Keep UI calm, premium, and intentional. Avoid generic AI-looking layouts, clutter, weak hierarchy, and gratuitous animation.
- Do not use emojis in product UI unless the user explicitly requests them.
## Component Selection Order
When building or revising UI, check these sources before writing custom components:
1. Magic UI MCP if it is available in the session.
2. shadcn or shadcn-solid resources available in the session or project.
3. `/home/tdvorak/.codex/skills/frontend-design/SKILL.md` when the task is design-heavy or starts from a blank canvas.
4. Existing project components and patterns in the repository.
Create custom UI only after those checks or when none of them fit.
## Delivery Standard
Ship work that feels like serious modern software rather than a prototype. If the result looks generic, crowded, inconsistent, or under-structured, redesign it before finishing.
.blackbox/skills/tdvorak-fullstack/agents/openai.yaml
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "TDvorak Fullstack"
short_description: "Personal SaaS full-stack build standards"
default_prompt: "Use $tdvorak-fullstack to build or extend this project with the preferred SolidJS, Go, PostgreSQL, and SaaS-grade product standards."
.blackbox/skills/tdvorak-fullstack/references/architecture.md
+83
View File
@@ -0,0 +1,83 @@
# Architecture Defaults
Read this file when choosing stack, scaffolding a new codebase, or making backend, auth, database, or infrastructure decisions.
## Stack Defaults
- Default to SolidJS for new frontend work.
- Fall back to React when Solid would materially slow delivery, block needed libraries, or fight the existing project.
- Use Vite, TypeScript, and Tailwind CSS on the frontend.
- Prefer Ark UI for Solid and shadcn or shadcn-solid when they fit the project.
- Support responsive layouts, dark and light mode, and accessibility by default.
## Authentication
- Use Better Auth when authentication is required.
- Prefer secure cookie sessions.
- Model user accounts first, then add organizations, teams, roles, or API tokens when the product requires them.
## Backend
- Default to Go for backend services.
- Use Gin for HTTP APIs.
- Use zap for structured logging.
- Keep packages small and focused.
- Avoid framework magic and hidden behavior.
- Keep routing, business logic, and data access explicit.
- Introduce Rust or Python only when the task has a clear technical reason for it.
## API Contract
- Treat OpenAPI as the single source of truth.
- Generate the TypeScript client, shared API types, and request helpers from the OpenAPI spec.
- Do not duplicate API types manually in frontend code.
- Keep request and response shapes aligned with generated artifacts.
## Database
- Use PostgreSQL as the default database.
- Use sqlc for type-safe query generation.
- Use goose for migrations.
- Apply schema changes through versioned migrations only.
- Do not edit production schemas manually.
## Infrastructure
- Make the project runnable with `docker compose up`.
- Use Docker and Docker Compose as the default local orchestration layer.
- Include the application, database, and reverse proxy when the product needs them.
- Use Nginx or Traefik for TLS termination, routing, static file serving, and load balancing.
## Desktop and Mobile
- Use Wails for Go-centric desktop apps. Use Tauri when it is a better technical fit.
- Keep the desktop frontend aligned with the web frontend when possible.
- Use React Native for mobile apps.
- Reuse the same backend APIs and design language across web, desktop, and mobile surfaces.
## Project Layout
Use this structure for greenfield full-stack projects unless the repository already has a better-established layout:
```text
/apps
/frontend
/backend
/packages
/api-client
/shared-types
/infra
docker-compose.yml
nginx
```
Keep frontend and backend concerns clearly separated.
## Code Quality
- Use strict TypeScript.
- Use clear naming and small focused functions.
- Preserve clean module boundaries.
- Favor maintainability and predictability over clever abstractions.
.blackbox/skills/tdvorak-fullstack/references/ui-standards.md
+59
View File
@@ -0,0 +1,59 @@
# UI Product Standards
Read this file when designing screens, choosing components, or judging whether a UI is ready to ship.
## Product Bar
- Build interfaces that feel like real production software, not prototypes.
- Optimize for consistent layout, clear hierarchy, predictable UX, strong performance, and scalable composition.
- Keep the interface calm, premium, structured, and intentional.
## Design Direction
- Use generous whitespace and a steady layout rhythm.
- Keep typography clean, readable, and deliberate.
- Use refined color with restraint.
- Prefer modern minimalism over visual noise.
- Avoid cluttered layouts, inconsistent spacing, and generic AI-looking compositions.
## Component Strategy
- Use a design-system-first mindset.
- Check Magic UI MCP first when it is available.
- Check shadcn or shadcn-solid before building custom components.
- Read `/home/tdvorak/.codex/skills/frontend-design/SKILL.md` for design-heavy or blank-canvas frontend work.
- Inspect existing project components before creating something new.
- Use Tailwind utilities where practical and prefer composition over custom overrides.
## Interaction and Motion
- Use subtle transitions, clear hover states, and responsive feedback.
- Keep animation in service of clarity rather than decoration.
- Avoid heavy or distracting motion.
- Prioritize performance.
- Use `https://haptics.lochie.me/` as a motion reference when useful.
## Quality Targets
Aim for the polish level associated with products such as Linear, Vercel, Stripe Dashboard, Supabase, and Notion without copying them directly.
## UI Rules
- Make layouts mobile responsive by default.
- Support dark and light mode unless the task clearly does not need both.
- Keep components accessible.
- Use a predictable spacing scale and consistent border radii.
- Avoid emojis in the UI unless the user explicitly asks for them.
## Final Review
Before finishing, confirm that the interface has:
1. Clean whitespace
2. Consistent spacing
3. Readable typography
4. Strong visual hierarchy
5. Balanced layout
6. Responsive behavior
If the result still looks generic or autogenerated, redesign it.