frontend-guidelines

Core frontend coding standards for HTML, CSS, and JavaScript/TypeScript. Use when writing, reviewing, or refactoring any HTML markup, CSS styles, or JS/TS code in this repo. Triggers on phrases like "follow our frontend guidelines", "review this component", "check my markup", "audit this CSS", "is this idiomatic", or whenever editing files under `src/**`, `public/**`, or any `.html`, `.css`, `.ts`, `.tsx`, `.js`, `.jsx` file. Apply automatically when authoring new components, fixing styles, or refactoring JS logic.

Jump to install

Repository: ohcnetwork/careui
Last source activity: May 17, 2026 at 17:06
Detected SKILL.md language: English
Stars: 3
Forks: 4

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	frontend-guidelines
description	Core frontend coding standards for HTML, CSS, and JavaScript/TypeScript. Use when writing, reviewing, or refactoring any HTML markup, CSS styles, or JS/TS code in this repo. Triggers on phrases like "follow our frontend guidelines", "review this component", "check my markup", "audit this CSS", "is this idiomatic", or whenever editing files under `src/`, `public/`, or any `.html`, `.css`, `.ts`, `.tsx`, `.js`, `.jsx` file. Apply automatically when authoring new components, fixing styles, or refactoring JS logic.
metadata	{"version":"1.0.0","source":"Frontend Guidelines (internal)"}

Frontend Guidelines

Authoritative coding standards for HTML, CSS, and JavaScript/TypeScript in this repository.

When to apply

Apply these rules automatically when:

Writing or editing any .html, .css, .ts, .tsx, .js, .jsx file
Creating new UI components in src/components/
Reviewing PRs or auditing code for quality
Refactoring existing markup, styles, or logic

Precedence

If a rule here conflicts with .github/copilot-instructions.md or a more specific repo skill (e.g. shadcn, web-design-guidelines), the repo-specific instruction wins. These are baseline craft standards.

Self-check before finishing any task

Before declaring work complete, verify:

HTML

Hard rules

Use semantic elements — <main>, <article>, <header>, <nav>, <section>, <time>, <button>, <label>. Never use <div class="button">.
Don't misuse semantics — wrong semantic is worse than neutral. Only wrap content in an element if it matches that element's meaning.
Be terse — omit type="text/css", type="text/javascript", XHTML self-closing slashes, and redundant Content-Type meta when <meta charset> exists.
Always declare <html lang> and <meta charset=utf-8>.
Accessibility is not optional — meaningful alt, real <button> / <a> (never <div role="button">), never rely on color alone, label every form control, ensure visible focus (:focus-visible), and meet WCAG 2.2 AA contrast.
Don't block rendering — use defer (or type="module") for scripts; async only for independent ones. Put non-critical scripts at the end of <body>.
Image performance — always set width/height (prevents CLS), use loading="lazy" below the fold, decoding="async", and fetchpriority="high" for the LCP image.
Quote attributes consistently. HTML5 allows unquoted values, but quoting (<input type="email">) is the team default and is required in JSX.

Examples

<!-- ❌ bad -->
<div id="main">
  <div class="article">
    <div class="header"><h1>Post</h1><p>Published: <span>21 Feb 2015</span></p></div>
  </div>
</div>

<!-- ✅ good -->
<main>
  <article>
    <header>
      <h1>Post</h1>
      <p>Published: <time datetime="2015-02-21">21 Feb 2015</time></p>
    </header>
  </article>
</main>

<!-- ❌ render-blocking -->
<script src="analytics.js"></script>
<title>Hello</title>
<p>...</p>

<!-- ✅ deferred -->
<title>Hello</title>
<p>...</p>
<script src="analytics.js"></script>

CSS

Hard rules

Terminate every declaration with a semicolon.
Set box-sizing globally (* { box-sizing: border-box }); don't toggle per-element.
Stay in normal flow — avoid position: absolute and display: block overrides when alignment/spacing utilities work.
Prefer Flexbox / Grid for layout.
Keep selectors shallow — if you need >3 combinators or pseudo-classes, add a class instead.
Minimize specificity — no !important, avoid IDs as style hooks. Compose classes (.foo.bar) over overriding.
Don't override styles you just set — write the targeted rule directly (li + li vs li {} then li:first-child {}).
Use inheritance — declare on the parent, not every child.
Use shorthand (padding: 5px 10px 20px, transition: 1s).
Unitless when possible (line-height: 1.5, margin: 0); prefer rem for relative units; use clamp() for fluid type. Seconds over ms.
Animations: transitions over keyframes; primarily animate opacity and transform (compositor-friendly). Always honor @media (prefers-reduced-motion: reduce).
Vendor prefixes: don't hand-write them. Modern targets (last 2 Chrome/Firefox/Safari/Edge) need almost none — Autoprefixer / Lightning CSS handles the rest.
Colors: use design tokens / CSS variables (var(--color-primary)). For new color literals prefer oklch() (perceptually uniform, what Tailwind v4 uses) or hsl() over hex. color-mix() for tints/shades. Reserve raw hex for one-off legacy values.
Use modern layout tools — gap for Flex/Grid spacing (not margins between siblings), logical properties (margin-inline, padding-block) for i18n, container queries (@container) over media queries when scoping to a component.
Don't ship hacks — no commented-out rules left behind, no GPU hacks; use only on elements about to animate, and remove it after.

Examples

/* ❌ */ .bar { color: green !important; } .foo { color: red; }
/* ✅ */ .foo.bar { color: green; } .foo { color: red; }

/* ❌ */ li { visibility: hidden; } li:first-child { visibility: visible; }
/* ✅ */ li + li { visibility: hidden; }

/* ❌ */ div:hover { animation: move 1s forwards; } @keyframes move { 100% { margin-left: 100px; } }
/* ✅ */ div:hover { transition: 1s; transform: translateX(100px); }

/* ❌ */ div { margin: 0px; font-size: .9em; line-height: 22px; transition: 500ms; }
/* ✅ */ div { margin: 0; : .; : ; : .; }

JavaScript / TypeScript

Hard rules

Readability > micro-perf. JS is rarely the bottleneck. Optimize images, network, DOM reflows, and bundle size — not loop counters.
Pure functions by default — no hidden side effects, return new objects rather than mutating inputs. Use structuredClone(x) for deep copies.
Use natives (Array.from, Object.assign, Object.hasOwn, Object.groupBy, structuredClone, Map, Set, URL, URLSearchParams, AbortController) before reaching for libraries. Don't feature-detect ES2015+ — it's universal.
const > let > var. Never use var in new code.
Strict equality (=== / !==). The only acceptable loose comparison is x == null to check for null-or-undefined, and even that is optional.
Prefer array methods (map / filter / reduce / flatMap) when they express intent. for...of is fine when you need early break, await in the loop, or side effects. Avoid C-style for (let i = 0; i < ...) and forEach with side effects.
Rest/spread instead of arguments and apply().
Arrow functions for lexical this instead of .bind(this).
Avoid nesting — pass functions by reference (.map(String) not .map(x => String(x))).
Optional chaining + nullish coalescing (a?.b ?? fallback) over && chains and || defaults (which mishandle 0 / "").
Object.hasOwn(obj, key) instead of Object.prototype.hasOwnProperty.call(obj, key) or obj.hasOwnProperty(key).

TypeScript rules

No any. Use unknown and narrow, or define a proper type. as casts only at trust boundaries.
Prefer type for unions/aliases, interface for extensible object shapes. Be consistent with file's existing style.
satisfies for literal values that should match a type without widening (e.g. config objects).
readonly on props and config that shouldn't mutate. as const for literal tuples/objects.
Discriminated unions over optional-everywhere shapes for state machines / variant props.
Don't re-export types with export *; be explicit.

Examples

// ❌ imperative
const result = [];
for (let i = 0; i < arr.length; i++) {
  if (arr[i] % 2 === 0) result.push(arr[i] * arr[i]);
}

// ✅ declarative
const result = arr.filter(n => n % 2 === 0).map(n => n * n);

// ❌ mutates input
const merge = (target, ...sources) => Object.assign(target, ...sources);

// ✅ pure
const merge = (...sources) => Object.assign({}, ...sources);

// ❌ apply
greet.apply(null, person);
// ✅ spread
greet(...person);

// ❌ bind
const full = function () { return `${this.first} ${this.last}`; }.bind(this);
// ✅ arrow
const full = () => `${this.first} ${this.last}`;

// ❌ pulls in underscore
import _ from "underscore";
_.unique(arr);

// ✅ native
const unique = arr => [...new Set(arr)];

// ❌ obfuscated
const n = ~~3.14;
foo || doSomething();

// ✅ explicit
const n = Math.floor(3.14);
if (!foo) doSomething();

// ❌ any + truthy default that breaks on 0/""
function greet(user: any) {
  const name = user.name || "Guest";
}

// ✅ typed + nullish coalescing + optional chaining
type User = { name?: string };
function greet(user: User) {
  const name = user.name ?? "Guest";
}

// ❌ widens to string
const config = { theme: "dark", direction: "ltr" };

// ✅ keeps literal types
const config = { theme: "dark", direction: "ltr" } as const;
// or, when validating against a type:
const config = { theme: "dark", direction: "ltr" } satisfies AppConfig;

React 19 specifics

No forwardRef for new components. In React 19, ref is a regular prop on function components — destructure it directly.
No React.FC. Type props inline or via a Props type/interface.
Stable keys in lists — never array index when items can reorder.
use() for unwrapping promises/contexts in render, when appropriate.
Server Actions / form actions over manual onSubmit + fetch when applicable.
Memoize sparingly — useMemo / useCallback / memo only with a measured reason. The React Compiler (when enabled) handles most cases.
Effects are for synchronizing with external systems, not for deriving state. Compute derived values during render.
Cleanup every subscription / timer / AbortController in useEffect return.

Repo-specific (CareUI)

This repo is React 19 + TypeScript + Tailwind v4. The JS rules above still apply, with these clarifications:

Component variants use CVA (class-variance-authority) — see src/components/ui/button.tsx.
Styling is via Tailwind utility classes, not custom CSS files. The CSS rules above govern any hand-written CSS in src/index.css and theme tokens (which use oklch).
Use the cn() helper from src/lib/utils.ts for conditional class composition.
Follow conventions in .github/copilot-instructions.md for component structure, registry workflow, and imports.

transform: translateZ(0)

will-change