---

name: frontend description: "Practitioner-grade reference knowledge for modern frontend development. Covers HTML semantics, CSS custom properties and design tokens, Tailwind CSS, WCAG 2.1 AA accessibility baseline, Core Web Vitals, asset optimization, and framework-agnostic JavaScript baseline. Activate when authoring or reviewing HTML, CSS, Tailwind configuration, accessibility audits, performance budgets, or any UI implementation concern that is not tied to a specific framework." license: Apache-2.0 compatibility: "No runtime prerequisites; this skill is documentation-only." metadata: provenance: canonical: "https://github.com/crewrig/crewrig" feedback: "https://github.com/crewrig/crewrig" version: "1.0.2"

Frontend

Practitioner reference for modern, framework-agnostic frontend work. Activate whenever the change touches HTML, CSS, design tokens, Tailwind configuration, accessibility, asset delivery, or vanilla JavaScript concerns that are not bound to a specific framework. Framework wiring (Astro, React, Vue, Svelte) belongs to its dedicated specialist — this skill stops at the platform boundary.

When to activate

• Writing or reviewing HTML markup, including semantic structure and forms.
• Authoring CSS, design tokens, or Tailwind configuration.
• Running an accessibility audit against WCAG 2.1 AA.
• Diagnosing Core Web Vitals regressions (LCP, CLS, INP).
• Optimizing fonts, images, or script loading.
• Writing framework-agnostic JavaScript: observers, fetch, ES modules.

HTML semantics

Semantics are the cheapest accessibility win and the foundation every later layer depends on. Generic <div> soup forces you to bolt ARIA back on; semantic elements come with the correct role, focus behavior, and assistive-tech mapping for free.

Document outline

Each page has exactly one <h1> — typically the hero title. Heading levels descend without gaps (h1 → h2 → h3). Screen readers expose a heading tree; gaps and duplicate h1 tags break that navigation.

Landmark roles

Wrap the page in landmark elements rather than <div>s. Each landmark appears in the AT rotor and gives keyboard users a skip target.

<body>
  <a class="skip-link" href="#main">Skip to content</a>
  <header><nav aria-label="Primary">…</nav></header>
  <main id="main">
    <article>
      <h1>Page title</h1>
      <section aria-labelledby="features">
        <h2 id="features">Features</h2>
      </section>
    </article>
    <aside aria-label="Related">…</aside>
  </main>
  <footer>…</footer>
</body>

Semantic element checklist

• <button> for in-page actions; <a href> for navigation.
• <nav> for navigation groups; label with aria-label when more than one exists on the page.
• <main> once per page; everything outside lives in <header>, <aside>, or <footer>.
• <figure> + <figcaption> for images that need attribution or a caption.
• <time datetime="…"> for machine-readable dates.
• <dl> / <dt> / <dd> for definition lists and key/value pairs.

Forms

• Every input has a <label for> (or wraps the input). Placeholders are not labels.
• Group related inputs in <fieldset> with a <legend>.
• Use the right type (email, tel, url, number, date) — it drives mobile keyboards, validation, and assistive announcements.
• Use autocomplete tokens (name, email, current-password, one-time-code) — password managers and AT depend on them.
• Surface validation errors with aria-invalid="true" and aria-describedby pointing to the error message.

CSS

Custom properties and design tokens

CSS custom properties are the runtime substrate for design tokens. They cascade, can be themed at any DOM depth, and respond to media queries — which :root-only Sass variables cannot.

:root {
  --primitive-color-white:    #ffffff;
  --primitive-color-blue-400: #60a5fa;
  --primitive-color-blue-500: #3b82f6;
  --primitive-space-4: 1rem;

  --color-accent:    var(--primitive-color-blue-500);
  --color-on-accent: var(--primitive-color-white);
  --space-md: var(--primitive-space-4);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-accent:    var(--primitive-color-blue-400);
    --color-on-accent: var(--primitive-color-white);
  }
}

Container queries

Container queries let a component respond to its container, not the viewport. Prefer them for reusable components that may live in sidebars, modals, or full-width layouts.

.card-host {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 32rem) {
  .card {
    grid-template-columns: 1fr 2fr;
  }
}

@layer

Cascade layers let you order origins explicitly and stop specificity arms races. Declare the order once at the top of the entry stylesheet.

@layer reset, tokens, base, components, utilities;

@layer components {
  .button { /* … */ }
}

Tailwind's base, components, utilities map onto this model.

Logical properties

Use logical properties (margin-inline, padding-block, border-inline-start, inset-inline-end) instead of physical (left / right). They flip automatically under direction: rtl and writing-mode: vertical-rl.

Fluid typography with clamp()

:root {
  --font-size-h1: clamp(2rem, 1.5rem + 2.5vw, 3.5rem);
}

clamp(min, preferred, max) removes most named breakpoints for typography. Pair the preferred value with a viewport-relative term so it scales between the bounds.

Dark mode

Prefer prefers-color-scheme and token swaps over .dark class toggling unless the product needs an explicit user override.

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: #0b0f17;
    --color-text: #e6edf3;
  }
}

When a manual override is required, gate the swap on a data-theme="dark" attribute on <html> and persist the choice in localStorage.

Design systems

Token taxonomy

Three layers, in this order:

1. Primitive — raw values, no meaning. Prefix with --primitive-color-*, --primitive-space-*, --primitive-font-*. Never reference primitives directly from components.
2. Semantic — intent-bound aliases of primitives. --color-accent, --color-surface, --space-md, --radius-card. Components consume only this layer.
3. Component — local tokens scoped to a component. --button-bg, --button-padding-inline. Defined inside the component scope, defaulted from semantic tokens.

.button {
  --button-bg: var(--color-accent);
  --button-fg: var(--color-on-accent);
  background: var(--button-bg);
  color: var(--button-fg);
}

.button[data-variant="ghost"] {
  --button-bg: transparent;
  --button-fg: var(--color-accent);
}

This taxonomy is what makes a design system theme-able. Swap primitives to rebrand; swap semantics to retheme; swap component tokens to vary a single component.

Tailwind CSS

Configuration extension

Tailwind's defaults are the floor, not the ceiling. Extend with theme.extend so you keep the defaults and add tokens; replace theme.colors only when you have a complete palette.

// tailwind.config.js
export default {
  content: ['./src/**/*.{html,js,ts,astro,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        accent: {
          DEFAULT: 'var(--color-accent)',
          fg: 'var(--color-on-accent)',
        },
      },
      spacing: {
        gutter: 'var(--space-md)',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
};

Reference CSS custom properties from the config — that keeps Tailwind utilities theme-aware without rebuilding.

@apply vs utility-first

Default to utility-first in markup. Reach for @apply only when:

• The same utility cluster repeats in three or more places and the cluster names a real concept (.button, .card).
• A third-party component (CMS, email) cannot accept utilities.
• You need a selector that utilities cannot express (:has, :nth-child, complex @container).

@apply chains longer than ~8 utilities are a smell — extract a component layer rule instead.

JIT and content scanning

Tailwind v3+ runs JIT by default; the only knob that matters is content. Misconfigured globs are the number-one cause of "my class does not apply" reports.

• Include every file extension where class names can appear.
• Avoid dynamic class concatenation (bg-${color}) — JIT cannot see it. Use a safelist or a lookup map of full class names.

Plugin authoring

Plugins are the right tool when you need utilities the core does not ship (focus-visible variants, custom typography, design-system shortcuts). Stay framework-agnostic — emit CSS, not JavaScript.

import plugin from 'tailwindcss/plugin';

export default plugin(({ addUtilities, theme }) => {
  addUtilities({
    '.text-balance': { 'text-wrap': 'balance' },
    '.focus-ring': {
      'outline': '2px solid transparent',
      'outline-offset': '2px',
      '&:focus-visible': {
        'outline-color': theme('colors.accent.DEFAULT'),
      },
    },
  });
});

Accessibility — WCAG 2.1 AA

WCAG 2.1 AA is the legal baseline in most jurisdictions and the practical baseline everywhere else. Treat it as a floor, not a goal.

Focus management

• Every interactive element has a visible :focus-visible style. Remove the default outline only if you replace it with something at least as legible.
• Focus order follows the visual order. tabindex="0" makes a non-interactive element focusable; never use positive tabindex values.
• After a route change or modal open, move focus to the new context (the modal title, the page heading).

Skip links

Provide a skip link as the first focusable element. Style it visible on focus so it is discoverable.

.skip-link {
  position: absolute;
  inset-block-start: -100px;
  inset-inline-start: 0;
}

.skip-link:focus-visible {
  inset-block-start: 0;
}

aria-* attributes

The first rule of ARIA is: do not use ARIA. Pick the right semantic element first; reach for ARIA only when no element fits.

• aria-label / aria-labelledby — accessible name when the visible text is missing or ambiguous (icon-only buttons).
• aria-describedby — supplementary description (form hints, error messages).
• aria-expanded / aria-controls — disclosure widgets and menus.
• aria-current="page" — the active item in a navigation list.
• aria-live="polite" — status updates, toast regions.

Never set role="button" on a <div> when <button> would do.

Color contrast ratios

| Content | Minimum | |------------------------------------------------------------|---------| | Normal text (under 18 pt, or under 14 pt bold) | 4.5 : 1 | | Large text (18 pt+, or 14 pt+ bold) | 3 : 1 | | Non-text UI: icons, focus rings, form borders, separators | 3 : 1 | | Decorative / disabled UI | Exempt |

Verify with a contrast checker against the actual background, not the nominal one — gradients and translucent layers shift the result.

Touch targets

Interactive controls have a minimum hit area of 44×44 CSS pixels (WCAG 2.5.5 AAA, but practical baseline). When the visible target is smaller, expand the hit area with padding or a transparent pseudo- element — do not scale the visible glyph.

Core Web Vitals

Targets

| Metric | Good | Needs improvement | Poor | |-------------------------------------|----------|-------------------|----------| | LCP — Largest Contentful Paint | ≤ 2.5 s | ≤ 4.0 s | > 4.0 s | | CLS — Cumulative Layout Shift | ≤ 0.1 | ≤ 0.25 | > 0.25 | | INP — Interaction to Next Paint | ≤ 200 ms | ≤ 500 ms | > 500 ms |

INP replaced FID as a Core Web Vital in March 2024. It measu