diff --git a/.claude/skills/front-end-architect/SKILL.md b/.claude/skills/front-end-architect/SKILL.md index e803289..6d5f4b1 100644 --- a/.claude/skills/front-end-architect/SKILL.md +++ b/.claude/skills/front-end-architect/SKILL.md @@ -23,7 +23,7 @@ How you work: - Server entry: every project except apps has `src/server.ts`. - Critical: a fresh server render per request with no server cache, web vitals, bundle and chunk size, and hydration and navigation speed. -Read the playbook before designing or writing code: [references/b2c-b2b.md](references/b2c-b2b.md). When the work changes what the user sees or what search engines read (a page, template, organism, form, copy, upload, image, font, or metadata), also read [references/ui-rules.md](references/ui-rules.md): UX, SEO, images, and fonts. +Read the playbook before designing or writing code: [references/b2c-b2b.md](references/b2c-b2b.md). When the work changes what the user sees or what search engines read (a page, template, organism, form, copy, upload, image, font, icon, or metadata), also read [references/ui-rules.md](references/ui-rules.md): UX, SEO, images, fonts, and the icon sprite. ## 2. Stack @@ -42,7 +42,7 @@ Read the playbook before designing or writing code: [references/b2c-b2b.md](refe | Env | @t3-oss/env-core + valibot | The app validates its variables with `createClientEnv` and `createServerEnv` from `packages/libs/env`; other projects read only their own `env/`. No hard-coded env values | | Lint and format | oxlint, prettier | ESLint runs module-boundary rules only | | TS scripts and configs | jiti | Runs `tools/` scripts and TypeScript config files without a build step | -| Icons | svgo | Through island's `icon-sprite-plugin` | +| Icons | svgo | Through island's `icon-sprite-plugin`, into `symbol-defs.svg`, which no step hashes; linked with `?v=` | TanStack Query is implied by `configs/react-query.ts`; confirm the repo uses it before adding it. Don't add any dependency outside this stack without stating why and getting approval. @@ -128,6 +128,7 @@ Error handling, patterns, and refactoring have their own references. Read each o - Place every new component in three steps: reuse or add a variant first, then pick its level by what it renders and imports (never by its size), then its owner by whether it knows a domain. A domain-free organism that one route uses stays in that route's `organisms/` until a second route needs it, then moves to island. An organism or template that knows a domain and serves several routes, or the same route in several apps, goes to the platform's `screens/`, at the nearest route level they share. Details: [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes). - Components use semantic tokens (`--color-surface-card`, `--color-text-muted`, `--color-action-primary`) layered over primitive tokens in `theme.css`. That layering is what makes theming and dark mode possible without a rewrite. - Every component defines its variants, sizes, and states (default, hover, focus-visible, active, disabled, loading, error, selected) and its accessibility behavior. Enabled interactive elements show `cursor: pointer` and disabled ones `cursor: not-allowed`, built into the component so no page can forget them. +- Fonts and the icon sprite keep their fixed file names, such as `yekan-bakh-vf.woff2` and `symbol-defs.svg`, served from each app's `public/` as immutable. No build step hashes or renames them (not `next/font`, the bundler, or the CSS pipeline), so an unchanged file stays in every visitor's cache across deploys. Fonts have no version. The sprite is linked as `symbol-defs.svg?v=`, and every change to it raises `ICON_SPRITE_VERSION` in the same commit. Details: [references/ui-rules.md](references/ui-rules.md#fonts-and-the-icon-sprite). - Complex organisms are compound components (``, ``, ``) that share state through context, with slots or render props for the parts that vary per entity, such as cells, empty states, and toolbars. **Cross-cutting** @@ -194,6 +195,7 @@ Structure [ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list [ ] Each new or moved part went through rendering-patterns.md's "Choosing where a part loads"; every deferred part and its trigger is written in the PR [ ] The server render is the same for every visitor; every auth-dependent page or part renders in the browser behind a same-size skeleton, unless the developer asked otherwise and the PR says so +[ ] Fonts and the icon sprite keep fixed names that no step hashes; every sprite change raised ICON_SPRITE_VERSION in the same commit [ ] Refactors are in their own commits, and the PR states how unchanged behavior was checked; smells noticed but not fixed are listed as debt [ ] Code follows every accepted decision in docs/decisions; lasting decisions made in this work are recorded @@ -219,4 +221,4 @@ Every review comment names the rule, shows the problem, and proposes the fix. Fo Name a code smell and its technique, with the target layer or file, as [references/refactoring.md](references/refactoring.md#review-comments) does. A smell is a suggestion; when it also breaks a rule on the list below, lead with that rule, mark it blocking, and name the smell in the body. In a feature PR, raise smells only in the code the PR touches. Flag a pattern from the "Not used here" list in [references/design-patterns.md](references/design-patterns.md#not-used-here) with its alternative. Never flag the smells that refactoring.md marks as intended. -Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale. +Block a merge only for: code that breaks an accepted project decision; a boundary or layer violation; a client-side dependency in a repository; server-only code reachable from a client bundle; tokens or personal data readable by JavaScript (a non-HttpOnly cookie or local storage); stale cache after a mutation; a sprite change without a version bump, a font changed under its old name, or a font or sprite name that a build step hashes; missing error handling; missing loading or empty states; inaccessible contrast; UI that flickers on update; a server-side cache; a server render that depends on auth without the developer's explicit request; a page not rendered per request, or a web-vitals or bundle-budget regression. Everything else is a suggestion with a rationale. diff --git a/.claude/skills/front-end-architect/references/code-patterns.md b/.claude/skills/front-end-architect/references/code-patterns.md index 2c5bdfe..ec8d835 100644 --- a/.claude/skills/front-end-architect/references/code-patterns.md +++ b/.claude/skills/front-end-architect/references/code-patterns.md @@ -157,6 +157,26 @@ This is an excerpt. The real file defines every semantic token the components us @source '../'; ``` +`styles/fonts.css`. Each `src` is a root path to the file in the app's `public/fonts/`, so no build step renames it ([ui-rules.md](ui-rules.md#fonts-and-the-icon-sprite)). The fallback face is a local font resized to the web font's metrics, so the swap doesn't shift layout. Measure the override values once for each face, and list the fallback after the web font in `--font-sans` in `theme.css`. + +```css +@font-face { + font-family: 'Yekan Bakh'; + src: url('/fonts/yekan-bakh-vf.woff2') format('woff2'); + font-weight: 100 900; + font-display: swap; +} + +@font-face { + font-family: 'Yekan Bakh Fallback'; + src: local('Tahoma'); + size-adjust: 102%; + ascent-override: 95%; + descent-override: 28%; + line-gap-override: 0%; +} +``` + `apps//src/styles/app.css` ```css diff --git a/.claude/skills/front-end-architect/references/project-structure.md b/.claude/skills/front-end-architect/references/project-structure.md index 07034d0..aa4976d 100644 --- a/.claude/skills/front-end-architect/references/project-structure.md +++ b/.claude/skills/front-end-architect/references/project-structure.md @@ -21,7 +21,7 @@ Three folders are named `tools`. Keep them apart: - Root `tools/`: scripts that run in a terminal, in CI, or through Nx (generators, validators). App code never imports them. TypeScript scripts run with jiti. - `packages/tools/`: shared runtime tools that apps and projects import. -- `packages/island/src/tools/`: design-system tools such as `cn`, `cvx`, `icon-sprite-plugin`, and `icon-name-extraction`. +- `packages/island/src/tools/`: design-system tools such as `cn`, `cvx`, `icon-sprite-plugin`, `font-copy-plugin`, and `icon-name-extraction`. ## App (Next.js) @@ -208,7 +208,7 @@ packages/island/src/ ├── templates/ # like organisms ├── primitives/ # non-visual structural pieces, e.g. portal, error-boundary; like organisms ├── tools/ -│ └── / # e.g. cn, cvx, icon-sprite-plugin, icon-name-extraction +│ └── / # e.g. cn, cvx, icon-sprite-plugin, font-copy-plugin, icon-name-extraction │ ├── .ts or .tsx │ ├── types.ts │ ├── constants.ts @@ -217,16 +217,16 @@ packages/island/src/ │ ├── island.css # entry that apps import into their Tailwind v4 CSS │ ├── theme.css # primitive and semantic tokens │ ├── utilities.css # custom @utility definitions -│ └── fonts.css # @font-face rules for fonts/ +│ └── fonts.css # @font-face rules; root paths to public/fonts/, never relative ├── env/ # island's env: setEnv and getEnv, filled by the app's bootstrap │ ├── env.ts │ ├── types.ts │ └── index.ts ├── icons/ -│ ├── symbol-defs.svg # sprite generated by Icomoon +│ ├── symbol-defs.svg # sprite generated by Icomoon; linked as symbol-defs.svg?v= │ └── selection.json # Icomoon snapshot; re-import it into Icomoon to update the set ├── fonts/ # every app's fonts, e.g. yekan-bakh-vf.woff2 -├── constants.ts # island-level constants +├── constants.ts # island-level constants, e.g. ICON_SPRITE_VERSION, CRITICAL_FONT_URL ├── index.ts └── server.ts ``` @@ -245,7 +245,10 @@ Component module: Tools: -- `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/` folder. Build-time tools are imported only from build configs, never from app code. +- `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/icons/symbol-defs.svg`. +- `font-copy-plugin` is a build and dev plugin. It copies `fonts/` byte for byte into each app's `public/fonts/`. +- Neither plugin adds a hash or a version to a file name, and no later build step renames their files. The sprite's version lives only in its link ([ui-rules.md](ui-rules.md#fonts-and-the-icon-sprite)). Their output in `public/` is generated, so git ignores it. +- Build-time tools are imported only from build configs, never from app code. - `icon-name-extraction` extracts icon names from the Icomoon files, for example to type the `Icon` component's `name` prop. ## Choosing where a component goes diff --git a/.claude/skills/front-end-architect/references/ui-rules.md b/.claude/skills/front-end-architect/references/ui-rules.md index b3187f8..cad7add 100644 --- a/.claude/skills/front-end-architect/references/ui-rules.md +++ b/.claude/skills/front-end-architect/references/ui-rules.md @@ -1,16 +1,35 @@ # UI rules -UX, SEO, and asset rules for [b2c-b2b.md](b2c-b2b.md). Read it when you build or change what the user sees or what search engines read: a page, template, organism, form, copy, upload, image, font, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it. +UX, SEO, and asset rules for [b2c-b2b.md](b2c-b2b.md). Read it when you build or change what the user sees or what search engines read: a page, template, organism, form, copy, upload, image, font, icon, or metadata. Work only on repositories, caches, actions, stores, or libs doesn't need it. -Contents: Images, fonts, and CSS · SEO and i18n · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context +Contents: Images, fonts, and CSS (Fonts and the icon sprite) · SEO and i18n · Copy · Feedback · Stability · Loading, progress, and empty states · File uploads · Forms · Keyboard and context ## Images, fonts, and CSS - Use `next/image` with explicit dimensions and `sizes`. Never lazy-load the LCP image: give it `loading="eager"` and `fetchPriority="high"`, or `preload` when it's discovered late. `priority` is deprecated in Next.js 16. Everything below the fold stays lazy. -- Fonts come from `island/fonts` as variable woff2. Preload only the critical face, use `font-display: swap`, and use a size-adjusted fallback so the swap doesn't shift layout. `next/font/local` does both. +- Fonts come from `island/fonts` as variable woff2. Preload only the critical face, use `font-display: swap`, and give each face a size-adjusted fallback face so the swap doesn't shift layout ([code-patterns.md](code-patterns.md#tokens-and-tailwind-wiring)). Never use `next/font`: it renames the files (next section). - Reserve space for images, banners, ads, and embeds with fixed aspect ratios. - Register every project whose components use Tailwind classes as a source (see code-patterns.md). +### Fonts and the icon sprite + +Fonts and the icon sprite change rarely, and every page needs them. A hash in their file names changes whenever a build step changes its output, such as a Next.js or svgo upgrade or a new loader option, even when the file itself didn't change. Every visitor then downloads them again. So they keep fixed names, and only a developer decides when visitors download them again. + +- Names: fonts keep their own names, such as `yekan-bakh-vf.woff2`, and the sprite stays `symbol-defs.svg`. Each app serves them from `public/fonts/` and `public/icons/`. +- No step adds a hash to them or renames them: not the bundler, not the CSS pipeline, not `next/font` (it copies fonts to `_next/static/media/.woff2`), not `icon-sprite-plugin`, not a CDN upload. `fonts.css` names each file by its root path, `url('/fonts/yekan-bakh-vf.woff2')`, which Next.js leaves alone. A relative path such as `url('../fonts/...')` goes through the bundler and gets a hash. +- Fonts have no version. A font file never changes under its name: a changed font ships as a new file with a new name. +- The sprite has a version in its link, never in its file name: `/icons/symbol-defs.svg?v=1`. island `constants.ts` holds `ICON_SPRITE_VERSION` and the `ICON_SPRITE_URL` built from it, and the `Icon` atom points `` at `${ICON_SPRITE_URL}#${name}`. A new Icomoon import or a changed svgo config raises `ICON_SPRITE_VERSION` in the same commit. Never reuse or lower a version. +- The critical font's path lives in island `constants.ts` as `CRITICAL_FONT_URL`, and each root layout preloads it with `preload(CRITICAL_FONT_URL, { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })`. The preload URL must equal the one in `fonts.css`, or the browser downloads the font twice. +- Serve them as immutable. Next.js serves `public/` with `Cache-Control: public, max-age=0`, so the browser asks again on every visit. Add this to the `headers()` in `next.config.ts`, and keep the same header on the CDN. The CDN must keep the query string in its cache key, or a new `?v=` still gets the old sprite. + +```ts +const immutable = [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }]; + +// inside headers() +{ source: '/fonts/:path*', headers: immutable }, +{ source: '/icons/:path*', headers: immutable }, +``` + ## SEO and i18n - Build `generateMetadata` from `configs/seo.ts`: title, description, canonical URL, `hreflang` alternates, and Open Graph. Add JSON-LD for products, breadcrumbs, and the organization. Provide `sitemap.ts` and `robots.ts`.