bendc Frontend Guidelines
Triggers
Use this skill when the task benefits from foundational HTML, CSS, and vanilla JS craft guidance from the vendored bendc/frontend-guidelines checklist, including:
- Semantic HTML, document structure,
lang, charset, and meaningful elements (main, article, time, etc.)
- Accessibility basics called out upstream:
alt text, real links and buttons, not relying on color alone, labelling controls
- CSS structure: selector weight, avoiding unnecessary
!important, inheritance, shorthand, flow and layout (flex/grid over absolute positioning when appropriate)
- CSS performance habits: prefer
opacity / transform for animation; avoid animating layout-heavy properties (aligns with repo motion rules)
- Vanilla or legacy JS style: readability, native APIs, avoiding foot-guns called out in the upstream doc
Also load docs/ai/rules/frontend.md for any apps/* or packages/ui work in this monorepo.
Do not use when
- The task is strictly backend, migrations, or database-only work.
- You only need React / Next.js / App Router patterns — prefer
docs/ai/skills/nextjs-app-router/SKILL.md and framework docs.
- You only need Tailwind, design tokens, or shared
@asym/ui primitives — the upstream doc is not Tailwind-specific; follow docs/ai/rules/frontend.md first.
Precedence (this repo wins)
The full text of the upstream guide lives in references/readme-original.md. When that reference conflicts with the Precedence table below, follow the table.
| Topic |
Authoritative in this repo |
Tailwind, Maia/Zinc tokens, cn(), no arbitrary hex in components |
docs/ai/rules/frontend.md |
Motion timing, tokens, reduced motion, transition-all ban, route view transitions |
docs/ai/rules/frontend.md, docs/ai/skills/emil-design-engineering/SKILL.md, docs/ai/skills/anim/SKILL.md |
| General JavaScript / TypeScript code shape, control flow, helper extraction |
ESLint, TypeScript configuration, formatter output, and nearby source patterns — prefer explicit, straightforward code over upstream terseness, loop avoidance, recursion, or shorthand |
TypeScript types, strict, equality (===), linted patterns |
ESLint / TS config and existing code style — do not adopt upstream examples that rely on loose equality or patterns that fail lint here |
| React component structure, Server Components, hooks |
Next.js docs and docs/ai/skills/react-component-dev/SKILL.md |
Use the bendc guide as a second opinion on semantics, DOM clarity, CSS discipline, and readable JS. Do not copy upstream JavaScript advice about terseness, avoiding loops, recursion, composition, or shorthand unless it improves clarity under this repo's AGENTS.md conventions.
Workflow
- Confirm the surface is in scope (markup, styles, or JS where the upstream checklist applies).
- Load
references/readme-original.md (or skim the sections you need: HTML, CSS, JavaScript).
- Cross-check Precedence above before recommending a change that touches tokens, Tailwind, motion, JS/TS code shape, or TS types.
- For shared UI or app routes, reconcile recommendations with
docs/ai/rules/frontend.md and nearby components.
- Prefer small, evidence-based edits; do not rewrite large areas solely to match upstream brevity examples if repo style differs.
Checklist
See also
- Repo UI policy:
docs/ai/rules/frontend.md
- Motion craft:
docs/ai/skills/emil-design-engineering/SKILL.md, docs/ai/skills/anim/SKILL.md
- React component patterns:
docs/ai/skills/react-component-dev/SKILL.md
- Maintainer refresh notes:
references/upstream.md
1---2name: bendc-frontend-guidelines3description: HTML, CSS, and JavaScript craft guidelines from bendc/frontend-guidelines — semantics, a11y basics, selector discipline, motion-friendly CSS, and readable JS. Use for markup review, static HTML/CSS, email HTML, or general front-end hygiene; pair with repo frontend rules and TypeScript lint policy.4---56# bendc Frontend Guidelines78## Triggers910Use this skill when the task benefits from **foundational HTML, CSS, and vanilla JS** craft guidance from the vendored [`bendc/frontend-guidelines`](https://github.com/bendc/frontend-guidelines) checklist, including:1112- Semantic HTML, document structure, `lang`, charset, and meaningful elements (`main`, `article`, `time`, etc.)13- Accessibility basics called out upstream: `alt` text, real links and buttons, not relying on color alone, labelling controls14- CSS structure: selector weight, avoiding unnecessary `!important`, inheritance, shorthand, flow and layout (flex/grid over absolute positioning when appropriate)15- CSS performance habits: prefer `opacity` / `transform` for animation; avoid animating layout-heavy properties (aligns with repo motion rules)16- Vanilla or legacy JS style: readability, native APIs, avoiding foot-guns called out in the upstream doc1718**Also load** `docs/ai/rules/frontend.md` for any **`apps/*` or `packages/ui`** work in this monorepo.1920## Do not use when2122- The task is strictly backend, migrations, or database-only work.23- You only need **React / Next.js / App Router** patterns — prefer `docs/ai/skills/nextjs-app-router/SKILL.md` and framework docs.24- You only need **Tailwind, design tokens, or shared `@asym/ui` primitives** — the upstream doc is not Tailwind-specific; follow `docs/ai/rules/frontend.md` first.2526## Precedence (this repo wins)2728The full text of the upstream guide lives in **`references/readme-original.md`**. When that reference conflicts with the **Precedence** table below, **follow the table**.2930| Topic | Authoritative in this repo |31| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |32| Tailwind, Maia/Zinc tokens, `cn()`, no arbitrary hex in components | `docs/ai/rules/frontend.md` |33| Motion timing, tokens, reduced motion, `transition-all` ban, route view transitions | `docs/ai/rules/frontend.md`, `docs/ai/skills/emil-design-engineering/SKILL.md`, `docs/ai/skills/anim/SKILL.md` |34| General JavaScript / TypeScript code shape, control flow, helper extraction | ESLint, TypeScript configuration, formatter output, and nearby source patterns — prefer explicit, straightforward code over upstream terseness, loop avoidance, recursion, or shorthand |35| TypeScript types, `strict`, equality (`===`), linted patterns | ESLint / TS config and existing code style — **do not** adopt upstream examples that rely on loose equality or patterns that fail lint here |36| React component structure, Server Components, hooks | Next.js docs and `docs/ai/skills/react-component-dev/SKILL.md` |3738Use the bendc guide as **a second opinion** on semantics, DOM clarity, CSS discipline, and readable JS. Do not copy upstream JavaScript advice about terseness, avoiding loops, recursion, composition, or shorthand unless it improves clarity under this repo's `AGENTS.md` conventions.3940## Workflow41421. Confirm the surface is in scope (markup, styles, or JS where the upstream checklist applies).432. Load **`references/readme-original.md`** (or skim the sections you need: HTML, CSS, JavaScript).443. Cross-check **Precedence** above before recommending a change that touches tokens, Tailwind, motion, JS/TS code shape, or TS types.454. For shared UI or app routes, reconcile recommendations with **`docs/ai/rules/frontend.md`** and nearby components.465. Prefer small, evidence-based edits; do not rewrite large areas solely to match upstream brevity examples if repo style differs.4748## Checklist4950- [ ] Confirmed triggers match (HTML/CSS/JS craft vs pure React/Next/backend).51- [ ] Read the relevant sections of `references/readme-original.md` or the live upstream README.52- [ ] Applied **Precedence**: repo frontend rules, motion skills, `AGENTS.md` code style, and TypeScript lint are satisfied.53- [ ] Did not strip accessibility or semantics for brevity.54- [ ] If you edited files under `docs/ai/skills/bendc-frontend-guidelines/`, ran `bun run skills:sync` and `bun run skills:verify` before committing.5556## See also5758- **Repo UI policy:** `docs/ai/rules/frontend.md`59- **Motion craft:** `docs/ai/skills/emil-design-engineering/SKILL.md`, `docs/ai/skills/anim/SKILL.md`60- **React component patterns:** `docs/ai/skills/react-component-dev/SKILL.md`61- **Maintainer refresh notes:** `references/upstream.md`
asymmetric-al