boxel: Skill for Claude Code

.gts Component Conventions

Two things live here:

1. Design-review guidelines (from Burcu) for component markup and CSS — apply when writing or reviewing any .gts component or <style scoped> block.
2. content-tag <template> hazards — the parser gotchas that silently drop or mangle a template. Read part 2 the moment a .gts file fails to type-check or lints with phantom errors after an edit.

Root font-size is the browser default 16px, so 1rem === 16px. There is no html { font-size } override.

---

Part 1 — Component & CSS guidelines

1. Target DOM elements with data-* attributes, not class names

Class names are a styling concern; JS that reaches into the DOM (closest, querySelector, matches, hasAttribute) should key off a data-* attribute so refactoring CSS classes never breaks behavior. Keep the class for the <style> selector and add a data-* marker for the JS hook.

// Wrong — JS coupled to a styling class
let marker = el.closest('.adorn-context');

// Right — class stays for CSS; data attribute is the JS contract
let marker = el.closest('[data-adorn-context]');

<div class='adorn-context' data-adorn-context ...attributes>

data-test-* attributes (used by the test suite) already follow this — extend the same habit to runtime DOM lookups.

2. Use scalable units (rem) instead of px

Convert dimensional CSS values — width/height, padding, margin, gap, border-radius, font-size, box-shadow spreads, clip-path offsets, positioning insets — to rem (divide px by 16). Prefer the existing --boxel-sp-*, --boxel-font-*, and radius tokens when one fits.

gap: 0.3125rem; /* was 5px */
padding: 0.1875rem 0.4375rem; /* was 3px 7px */
font-size: 0.625rem; /* was 10px */
box-shadow: 0 0 0 0.125rem var(--c); /* was 2px */

Leave as-is: SVG-internal coordinates (viewBox, cx, r, stroke-width, path d), and JS pixel math against getBoundingClientRect() — those aren't CSS layout units. Hairline values like letter-spacing: 0.5px are fine to leave (converting gains nothing).