agentleFS
the-hyve-companythe-hyve-company/design-factory-app/skills/frontend-guidelines/SKILL.md

frontend-guidelines

Skill4 starsChanged 5 months agoApache-2.0View on GitHub

Opinionated, terse principles for writing clean HTML, CSS, and JavaScript — semantics, accessibility, performance, low-specificity CSS, transform-only animation, and stateless/functional JS. Use when authoring or reviewing frontend code, untangling CSS specificity, or replacing imperative loops and bind/apply with native and functional patterns.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. cigery-useio/useio-skills★ 103same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 8 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    write alt text that conveys purpose, not "image of …"

    line 72
  2. Very specific:

    use real <button> and <a> so keyboard and screen-reader behavior comes for free

    line 73
  3. Distinctive:

    never encode meaning in color alone — pair it with text, shape, or an icon

    line 74
  4. Very specific:

    Default display and positioning are usually what you want.

    line 146
  5. Distinctive:

    Prefer Flexbox and Grid for layout over taking elements off the flow.

    line 162
  6. Distinctive:

    Don't over-qualify when the extra specificity buys nothing.

    line 177
  7. Very specific:

    Avoid !important and #id selectors — they make later styles hard to override and turn debugging into a fight.

    line 189
  8. Distinctive:

    If a property inherits, declare it once on a common ancestor rather than repeating it on each child.

    line 229
  9. Distinctive:

    Use shorthand properties and compute related values inline instead of stacking longhand declarations or extra helper offsets.

    line 246
  10. Distinctive:

    Use the readable form of a value when one exists — keyword selectors, named rotations — over the equivalent arithmetic.

    line 269
  11. Very specific:

    Prefer transitions to keyframe animations, and restrict what you animate to opacity and transform.

    line 299
  12. Very specific:

    Use a hex value for opaque colors and rgb() with an alpha channel only when you need transparency.

    line 347
  13. Distinctive:

    When an array method would be a stretch, recursion is clearer than a mutable loop.

    line 484
  14. Distinctive:

    If a callback just forwards its argument to another function with the same shape, pass that function directly.

    line 554
  15. Very specific:

    Default to const. Use let only when you must reassign.

    line 600
  16. Very specific:

    When keys are added, removed, or counted at runtime, Map is clearer than poking properties onto a plain object — and .size is built in.

    line 643

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Frontend Guidelines

Inspired by Benjamin De Cock's frontend-guidelines (https://github.com/bendc/frontend-guidelines), which carries no explicit license. The principles below are re-stated in original wording and re-illustrated with original examples; no text or code from the source is reproduced verbatim. See NOTICE.md in this folder for provenance details.

A compact rulebook for hand-written HTML, CSS, and JavaScript. Each rule states the intent, then shows a weaker form against a preferred form. Optimize for clarity and maintainability first.

HTML

Use the right element for the job

The element vocabulary describes meaning, not just layout. Reach for the tag that names what the content is before falling back to a generic container.

<!-- weak: every box is a div -->
<div class="post">
  <div class="meta">
    <h2>Release notes</h2>
    <span>Mar 4, 2026</span>
  </div>
  <div class="body">…</div>
</div>

<!-- preferred: structure carries meaning -->
<article class="post">
  <header class="meta">
    <h2>Release notes</h2>
    <time datetime="2026-03-04">Mar 4, 2026</time>
  </header>
  <div class="body">…</div>
</article>

A misapplied semantic element is worse than a neutral container. If a tag's meaning doesn't match the content, don't force it.

<!-- weak: a logo is not a paragraph of emphasis -->
<strong><img src="brand.svg" alt="Acme" /></strong>

<!-- preferred: just the image, with a real alt -->
<img src="brand.svg" alt="Acme" />

Keep the markup lean

Drop boilerplate the parser doesn't need. Modern HTML lets you omit redundant attributes and some closing tags; quoting and explicit types are optional where they add nothing.

<!-- weak: ceremony left over from XHTML -->
<input type="text" required="required" autocomplete="off" />

<!-- preferred -->
<input type="text" required autocomplete="off" />

Treat accessibility as table stakes

You don't need to memorize the spec to make real gains. A few habits cover most cases:

  • write alt text that conveys purpose, not "image of …"
  • use real <button> and <a> so keyboard and screen-reader behavior comes for free
  • never encode meaning in color alone — pair it with text, shape, or an icon
  • bind every form control to a label
<!-- weak: a clickable div has no role, no focus, no keyboard -->
<div class="btn" onclick="save()">Save</div>

<!-- preferred -->
<button type="button" onclick="save()">Save</button>

Declare language and encoding

Set the document language on the root element and declare UTF-8 at the top of the document, even when a server header also sends it. Both belong on the page itself.

<!doctype html>
<html lang="en">
  <meta charset="utf-8" />
  <title>Status</title>
</html>

Don't let scripts block first paint

Content should reach the user before non-essential scripts run. Put deferred or analytics-style scripts after the content (or use defer), and inline only the styles needed for the first view.

<!-- weak: analytics blocks the page -->
<head>
  <script src="analytics.js"></script>
  <title>Status</title>
</head>
<body>
  <p>…</p>
</body>

<!-- preferred: content first, script last -->
<head>
  <title>Status</title>
</head>
<body>
  <p>…</p>
  <script src="analytics.js" defer></script>
</body>

CSS

Set the box model once, globally

Pick one box model for the whole document with a single universal rule, then stop fiddling with it per element. Per-element overrides make sizing unpredictable.

/* once, at the top of the sheet */
*,
*::before,
*::after {
  box-sizing: border-box;
}

/* then just author padding without re-declaring the model */
.card {
  padding: 1rem;
}

Stay in the normal flow

Default display and positioning are usually what you want. Don't change display or pull elements out with absolute positioning unless the layout genuinely requires it.

/* weak: absolute positioning to push right */
.badge {
  position: absolute;
  right: 0;
}

/* preferred: let auto margins do it in flow */
.badge {
  margin-left: auto;
}

Prefer Flexbox and Grid for layout over taking elements off the flow.

Keep selectors shallow and decoupled

Long chains of combinators and structural pseudo-classes tie your CSS to a fragile DOM shape. When a selector grows past a few combinators, add a class to the target instead.

/* weak: brittle, coupled to structure */
section > ul li:first-child > a ~ span { … }

/* preferred: name the thing you mean */
.nav-label { … }

Don't over-qualify when the extra specificity buys nothing.

/* weak */
ul > li:first-child { … }

/* preferred */
ul > :first-child { … }

Keep specificity low and overridable

Avoid !important and #id selectors — they make later styles hard to override and turn debugging into a fight. Reach the weight you need by combining classes, not by escalating.

/* weak: now everything below has to shout louder */
.cta {
  color: green !important;
}

/* preferred: a more specific class composition */
.btn.cta {
  color: green;
}
.btn {
  color: gray;
}

Write rules so you rarely override them

Structure your selectors so the common case is the rule and the exception is small, instead of setting a value everywhere and clawing it back.

/* weak: set on all, then undo the first */
li {
  display: none;
}
li:first-child {
  display: block;
}

/* preferred: target only the ones you mean to hide */
li + li {
  display: none;
}

Lean on inheritance

If a property inherits, declare it once on a common ancestor rather than repeating it on each child.

/* weak */
.card h2,
.card p {
  font-family: Inter, sans-serif;
}

/* preferred */
.card {
  font-family: Inter, sans-serif;
}

Be terse: shorthands and computed values

Use shorthand properties and compute related values inline instead of stacking longhand declarations or extra helper offsets.

/* weak */
.box {
  padding-top: 4px;
  padding-right: 8px;
  padding-bottom: 16px;
  padding-left: 8px;
  top: 50%;
  margin-top: -10px;
}

/* preferred */
.box {
  padding: 4px 8px 16px;
  top: calc(50% - 10px);
}

Say what you mean

Use the readable form of a value when one exists — keyword selectors, named rotations — over the equivalent arithmetic.

/* weak */
:nth-child(2n + 1) {
  transform: rotate(360deg);
}

/* preferred */
:nth-child(odd) {
  transform: rotate(1turn);
}

Prune dead vendor prefixes

Drop prefixes that no current browser needs. When a prefix is still required, write it before the standard property so the standard one wins.

/* preferred: prefixed first, standard last, nothing obsolete */
.scale {
  -webkit-mask-image: linear-gradient(black, transparent);
  mask-image: linear-gradient(black, transparent);
}

Animate only what's cheap to animate

Prefer transitions to keyframe animations, and restrict what you animate to opacity and transform. Animating layout properties forces reflow and stutters.

/* weak: animating margin reflows the page */
.panel:hover {
  animation: slide 0.3s forwards;
}
@keyframes slide {
  to {
    margin-left: 120px;
  }
}

/* preferred: transform is composited, no reflow */
.panel {
  transition: transform 0.3s;
}
.panel:hover {
  transform: translateX(120px);
}

Prefer sensible units

Drop the unit on zero. For relative sizing favor rem; for line height a unitless multiplier; for durations seconds read more naturally than milliseconds.

/* weak */
.t {
  margin: 0px;
  font-size: 14px;
  line-height: 20px;
  transition: 300ms;
}

/* preferred */
.t {
  margin: 0;
  font-size: 0.875rem;
  line-height: 1.5;
  transition: 0.3s;
}

Color format

Use a hex value for opaque colors and rgb() with an alpha channel only when you need transparency.

/* opaque */
.ok {
  color: #4caf50;
}

/* needs transparency */
.veil {
  background: rgb(0 0 0 / 0.5);
}

Draw simple shapes in CSS, don't fetch them

A circle, dot, or triangle is cheaper to draw with a pseudo-element than to download as an image. Save the HTTP request.

/* weak: a network request for a dot */
.status::before {
  content: url(dot.svg);
}

/* preferred */
.status::before {
  content: "";
  display: inline-block;
  width: 0.5rem;
  height: 0.5rem;
  border-radius: 50%;
  background: currentColor;
}

Avoid hacks

Skip magic declarations whose only job is to trip a rendering quirk. If you need a compositing hint, say so explicitly, and use real CSS comments.

/* weak: opaque trick + JS-style comment */
.layer {
  // bump to its own layer
  transform: translateZ(0);
}

/* preferred: intent is stated, comment is valid CSS */
.layer {
  /* promote to its own compositing layer */
  will-change: transform;
}

JavaScript

Readability beats micro-performance

JS is almost never the bottleneck — network, images, and DOM reflow are. Write the clear version; optimize bytes on the wire and layout thrash instead. If you take one rule from here, take this one.

// weak: hand-rolled loop chasing speed nobody will notice
function evenSquares(nums) {
  let out = [];
  for (let i = 0; i < nums.length; i++) {
    if (nums[i] % 2 === 0) out.push(nums[i] * nums[i]);
  }
  return out;
}

// preferred: intent is obvious
const evenSquares = (nums) => nums.filter((n) => n % 2 === 0).map((n) => n * n);

Keep functions pure

Aim for functions with no side effects: don't read hidden outside state, and return fresh values instead of mutating the inputs.

// weak: mutates the first argument
const apply = (state, patch) => Object.assign(state, patch);

// preferred: returns a new object
const apply = (state, patch) => ({ ...state, ...patch });

Reach for native methods first

The standard library covers most of what you'd otherwise hand-write. Use it before reinventing it.

// weak: manual array-like conversion
const toArray = (nodeList) => Array.prototype.slice.call(nodeList);

// preferred
const toArray = (nodeList) => Array.from(nodeList);

Use coercion deliberately

Implicit coercion is fine when it reads clearly and dangerous when it surprises. A loose equality check against null catches both null and undefined; reserve the trick for cases where that's exactly the intent.

// verbose
if (value === null || value === undefined) {
  /* … */
}

// concise, when the two-value check is the actual goal
if (value == null) {
  /* … */
}

Replace loops with array methods

Imperative loops push you toward mutable accumulators. Most loops are really a map, filter, or reduce.

// weak
function total(nums) {
  let sum = 0;
  for (const n of nums) sum += n;
  return sum;
}

// preferred
const total = (nums) => nums.reduce((a, b) => a + b, 0);

When an array method would be a stretch, recursion is clearer than a mutable loop.

// preferred: no mutable counter
const repeat = (fn, times) => {
  if (times <= 0) return;
  fn();
  repeat(fn, times - 1);
};

Prefer rest parameters to arguments

The rest parameter is named (self-documenting) and is a genuine array, so array methods just work.

// weak
function maxOf() {
  return Math.max.apply(null, Array.prototype.slice.call(arguments));
}

// preferred
const maxOf = (...nums) => Math.max(...nums);

Spread instead of apply

Spreading an array into a call is clearer than threading it through apply.

const point = [3, 7];
const place = (x, y) => `${x},${y}`;

// weak
place.apply(null, point);

// preferred
place(...point);

Avoid bind when an idiom exists

Arrow functions capture this lexically, so you rarely need bind to preserve context inside a method.

// weak
const counter = {
  count: 0,
  start() {
    const tick = function () {
      this.count++;
    }.bind(this);
    setInterval(tick, 1000);
  },
};

// preferred
const counter = {
  count: 0,
  start() {
    setInterval(() => {
      this.count++;
    }, 1000);
  },
};

Don't wrap a function that's already the function you want

If a callback just forwards its argument to another function with the same shape, pass that function directly.

// weak
["1", "2", "3"].map((s) => Number(s));

// preferred
["1", "2", "3"].map(Number);

Compose instead of nesting calls

Deeply nested calls read inside-out. A small composition helper reads left-to-right.

const inc = (n) => n + 1;
const double = (n) => n * 2;

// weak
double(inc(5)); // 12

// preferred
const pipe =
  (...fns) =>
  (x) =>
    fns.reduce((acc, fn) => fn(acc), x);
const incThenDouble = pipe(inc, double);
incThenDouble(5); // 12

Cache expensive work

Feature checks, big lookups, and other costly setup should run once and be reused, not repeated on every call.

// weak: probes support on every call
const supportsClipboard = () => "clipboard" in navigator;

// preferred: resolve once
const supportsClipboard = (() => "clipboard" in navigator)();

Prefer const, then let, never var

Default to const. Use let only when you must reassign. var has no place in new code.

// preferred
const ids = new Set();
let attempts = 0;

Prefer expressions to statement ladders

An IIFE with early returns reads better than a mutable variable threaded through if/else if/else.

// weak
let tier;
if (score < 50) tier = "low";
else if (score < 90) tier = "mid";
else tier = "high";

// preferred
const tier = (() => {
  if (score < 50) return "low";
  if (score < 90) return "mid";
  return "high";
})();

Avoid for...in for own properties

for...in walks the prototype chain. Iterate the keys you actually own.

// weak
for (const key in obj) {
  if (Object.hasOwn(obj, key)) handle(key);
}

// preferred
Object.keys(obj).forEach(handle);

Use a Map for dynamic key/value data

When keys are added, removed, or counted at runtime, Map is clearer than poking properties onto a plain object — and .size is built in.

// weak
const seen = {};
seen["a"] = 1;
Object.keys(seen).length; // 1

// preferred
const seen = new Map();
seen.set("a", 1);
seen.size; // 1

Don't over-curry

Currying has its place, but those places are uncommon. Don't split arguments into a chain of single-argument functions out of habit.

// weak
const add = (a) => (b) => a + b;
add(2)(3);

// preferred
const add = (a, b) => a + b;
add(2, 3);

Write the obvious form, not the clever one

Short-circuit side effects, bitwise floor tricks, and similar cleverness hide intent. Spell it out.

// weak
ready && init();
const n = ~~3.9;

// preferred
if (ready) init();
const n = Math.trunc(3.9);

Build small, reusable functions

Tiny composable helpers beat repeated inline expressions. Name the operation once and reuse it.

// weak
const lastItem = list[list.length - 1];

// preferred
const last = (arr) => arr[arr.length - 1];
last(list);

Keep dependencies minimal

A third-party package is code you don't own. Don't pull in a whole library for a one-liner you can write yourself.

// weak
import uniq from "lodash/uniq";
uniq([1, 1, 2]);

// preferred
const uniq = (arr) => [...new Set(arr)];
uniq([1, 1, 2]);

Adapted from Ben Delarre's frontend-guidelines (https://github.com/bendc/frontend-guidelines).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.