frontend
Use for frontend STRUCTURE and behavior — organizing components, state, and data access (typed service layer, stores, thin components), building list/table/filter views, forms, and modals, loading/emp
SKILL.mdskills/frontend/SKILL.md
GitHubFrontend
Goal: build well-structured, performant, good-UX frontends, and learn the user's preferences (component styles, layouts, patterns) over time so future work matches taste.
Step 1 — route to the reference file(s) and READ them first
The real content of this skill lives in topic reference files (indexed in
LEARNINGS.md beside this skill, when your copy keeps one). Pick by task — reading the
wrong-or-no file is how established conventions get reinvented badly:
| Task involves… | Read first |
|---|---|
| Any list/table view — building, altering, or filtering one | The project's list/table reference — the shared table/list component's rules, operator filtering, row actions, async list states |
| A new service/endpoint wire-up, types/enums, stores, persistence, routing/nav, legacy-UI migration | The project's architecture reference — service layer, shared-types traps, the storage helper, route/nav conventions |
| Public pages, SEO, or anything server-rendered | The project's SSR/public-pages reference — SSR foundation, client-only libs, the SPA-vs-SSR local-testing split |
| Field placement, permissions/edit surfaces, modal-vs-page, icons, maps, taste | The project's UI/UX reference — includes the light+dark verification rule |
| Performance / Lighthouse / SEO scores | web-performance.md — scripts/lh-audit.sh + the ordered remediation playbook |
| A stack other than the primary Vue 3 + Tabler one (e.g. R/Shiny) | other-stacks.md |
| User-facing text in a multi-language app — new strings, translation keys, locale formatting, RTL | i18n — the completeness gate and the surface inventory |
Keep one project reference file per topic beside this skill, named for the project and
topic, and route to it from this table. This install's project files are listed in
LOCAL.md beside this skill, when your copy keeps one — Project reference files.
Also check the sibling skills when the task touches their territory: tabler-ui (component exceptions — always, before using any Tabler interactive component) and design-guide (color/type/spacing decisions).
Step 2 — mirror the codebase before inventing
Read neighboring components/services/stores for the feature area first. The bar is "indistinguishable from the code around it" — a parallel pattern (a second modal style, a hand-rolled localStorage helper, a bespoke table) is a review reject even when it works.
Step 3 — structure the change
- Layered data access: API calls in a typed service class, state in stores, components thin — raw HTTP in a component leaks untyped, untestable coupling.
- Reusable, prop-driven components: one component parameterized by props (e.g. an add/edit modal switched by an optional id) over near-duplicates, so fixes land once.
- Performance: lazy-load heavy/rare views, code-split by route, keep large lists paginated/virtualized, memoize derived data, and watch bundle size when adding a library — each avoids shipping cost to every user for a minority feature.
- UX: loading, empty, AND error states for every async surface (the error branch is the one that gets forgotten — see the data-tables file); inline validation feedback; don't block the whole view on one slow call.
Step 4 — verify (hard gates, not suggestions)
- Light AND dark mode. Tabler theming means a change can look perfect in one and broken in the other (contrast, hardcoded colors, theme-reactive re-renders). Toggle both before showing anything.
- Built output when class names are composed dynamically. If the production build
runs PurgeCSS (or a Tailwind-style content scan), a runtime-composed class
(
`btn-${x}`) passes dev and unit tests but ships unstyled in prod. Any dynamic class composition → verify against the built (SSR) output (see tabler-ui's PurgeCSS exception; this install's build:LOCAL.mdbeside this skill, when your copy keeps one — Built output and PurgeCSS). - Show the UI as inline screenshots. The user reviews visuals, not prose — render the change (component harness or full stack) and screenshot it, both themes.
- Run the project's checks: lint (e.g. oxlint) + build are enforceable; when the main
branch is already red under the type-checker (vue-tsc), the bar is "no NEW errors in
my files" (this install's baseline:
LOCAL.mdbeside this skill, when your copy keeps one — Checks baseline). - Gate with PARALLEL vitest, the way CI runs it (plain
vitest run— never--no-file-parallelismas the merge gate). A services↔stores barrel import cycle only threw when the module graph was entered service-first, i.e. under CI's parallel run, and stayed invisible to every local serial run. - "The page renders" is not evidence a FORM is usable. A render check proves the route mounted; it says nothing about whether the field accepts input, validates, or submits. Exercise the interaction.
- A CSS fix that "looks right" is unverified — A/B it against the DOM. Confirm the rule you added is the one taking effect (computed styles, or toggle it off and back) rather than inferring causation from the screenshot having changed.
Reactivity and layout traps
Each of these ships a green build and a plausible-looking screenshot.
- Post-auth pages must be REMOUNT-SAFE. Adopting a session re-registers routes,
which remounts the page — a guard reading state that
onMountedhad just cleared bounced a successful booking back to the start, and state handed viarouter.replace(…, { state })arrived empty after the same remount. Assume any post-auth view mounts more than once. - Aggregates must not be derived from the loaded page. A total computed from the rows currently in memory silently becomes "total of page 1". Derive it from the source, not the slice you happen to be rendering.
- A composable with an
immediate: truewatcher runs BEFORE its ownconstis assigned — the watcher fires during setup, hitting the temporal dead zone of the very binding it references. Guard it, or dropimmediate. - Vue auto-casts
v-modelontype="number"— the model holds a number, so calling a string method on it throws at runtime while the template looks fine. - Money formatters must normalise negative zero at the boundary. Negating a zero sum
yields JavaScript's
-0, whichIntl.NumberFormatrenders as-$0.00. Normalise where the value is formatted, and test the zero/empty case explicitly. - Vue scoped CSS reaches a CHILD component's ROOT element — a scoped rule on the
parent styles the child's root, which makes
display: contentson that root a foot-gun (the element vanishes from the box tree while still matching the selector). - A flex/grid item's automatic minimum size silently defeats its own basis — the
default
min-width: autorefuses to shrink below content, so aflex-basisor1frtrack that should compress simply doesn't. Setmin-width: 0(ormin-height: 0). - A stubbed
Teleportcan silently stop repatching attributes inside it, so a test that stubs it stops observing updates the real component would make.
Common failure modes
- Hand-rolling a
<table>for a data list — if the app has a shared data-table/list component, every tabular list goes through it. Stop and read the project's list/table reference (this install's:LOCAL.mdbeside this skill, when your copy keeps one — Data tables and shared types). - Importing a backend-shared workspace types package's runtime values (enums) in the frontend — when that package carries decorator metadata (reflect-metadata / class-transformer), a value import white-screens the app at boot. Type-only imports only; redefine enums locally.
- Testing only in light mode / only in dev mode — dark-mode-only and prod-only breakage are both established bug classes in Tabler apps (carousel desync, PurgeCSS stripping).
.filter((item) => item.condition)on action-menu items — filtering on the function reference (always truthy) instead of calling it; shows every action regardless of permission. Invoke the condition.- Skipping loading/error branches on a new fetch — a swallowed failure renders a misleading "no data" empty state.
- Writing
wrapper.get(x).exists()in a spec — recorded four separate times, which is why it is here rather than in the journal.get()already throws when the element is missing, so.exists()is both redundant and a vue-tsc type error. Usefind(x).exists()to assert presence, orget(x)alone when you need the element. - Deriving a landing page from the user's "highest" role — render additively instead; picking a winner hides surfaces a multi-role user is entitled to.
- Showing shared data on a multi-tenant "all" view without labelling its owner — correct rows, unattributable to a person, read as someone else's data.
Before you call this done
- Read the routed reference file(s) and matched the existing convention.
- Async surfaces have loading + empty + error states.
- Verified in BOTH light and dark mode.
- If any class name is composed at runtime: verified against the BUILT output.
- Inline screenshots shared for anything visual.
- Lint + build green; no new vue-tsc errors in changed files.
Related skills
- plain-language: the words inside empty, loading and error states, and every other UI label.
- code-quality: the hard rules every component is held to — one responsibility per file (a single-file component's three blocks are the only exception, with its logic in composables), readable by a junior engineer, and one rhythm per kind of screen.
Capturing learnings
Accumulate frontend conventions and the user's taste as you go, in the learnings files. The
corpus is split by topic, indexed from LEARNINGS.md beside this skill, when your copy keeps
one (the table in Step 1 mirrors it). At the end of a session, when asked to update the
skills, or after frontend work: record structural conventions, component patterns that
worked, performance/UX decisions, and any referenced layouts/styles the user liked (and why)
into the most relevant reference file — dedupe/merge, tag by stack. When the user shares a
layout/site they like, record what about it appeals (structure, density, interaction). If a
file outgrows ~250 lines, split it further by topic behind a slim index (this install's
split rule: LOCAL.md beside this skill, when your copy keeps one — Capturing
learnings).