Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Testowanie

design-loop

/design-loop

Wdraża interfejs z projektu w Figmie w aplikacji Arkive i porównuje wynik z projektem, aż różnice zostaną usunięte.

Repozytorium
arkive ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
23.09.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 23.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Wdraża interfejs z projektu w Figmie w aplikacji Arkive i porównuje wynik z projektem, aż różnice zostaną usunięte.

Oryginalny opis (EN)

Use when: (1) implementing UI from a Figma design in a project that uses Arkive, (2) validating UI changes against a design or spec, (3) reviewing screens visually after a change. Enforces the loop: implement with existing components → regenerate showcase → load snapshot + design truth in the same turn → enumerate differences → fix or STOP-and-ask. Compares against fresh showcase output — no goldens or snapshot tests involved. Runs Gradle locally.

Jak działa

  1. Design truth — three tiers, use the best available
  2. Scope rules
  3. The loop
  4. Handoff — when the screen matches
  5. Red flags — STOP and ask
Sekcje z nagłówków SKILL.md, w oryginale · 105 linii, 901 słów
Podgląd SKILL.md
---
name: design-loop
description: 'Use when: (1) implementing UI from a Figma design in a project that uses Arkive, (2) validating UI changes against a design or spec, (3) reviewing screens visually after a change. Enforces the loop: implement with existing components → regenerate showcase → load snapshot + design truth in the same turn → enumerate differences → fix or STOP-and-ask. Compares against fresh showcase output — no goldens or snapshot tests involved. Runs Gradle locally.'
---

# Arkive Design Validation Loop

Validate UI against its design using Arkive's showcase output plus a **multimodal visual
comparison** — view the rendered snapshot and the design truth in the same turn and judge
whether they match. Read `references/arkive-cheatsheet.md` for
paths, filename conventions, and the showcase JSON shape.

This loop compares against the **freshly generated showcase**, never against goldens.
There is no reference image to record, delete, or go stale — every `generateShowcase` run
re-renders everything. `snapshotRetention` is irrelevant here (NONE is fine). Golden
verification is a different concern: `/arkive:snapshot-testing`.

**Two non-negotiable rules:**

- **Match is judged by eye**, not by a pixel-diff. "Matches" means that when you view both
  images in the same turn you cannot point to a visible difference. Figma and Paparazzi
  use different font renderers — pixel-identical is impossible and not the goal.
- **Never customize, duplicate, or replace a shared UI component just to match the
  design.** If the shared component can't produce what the design shows, STOP and ask.
  That is a product/design decision, not a coding problem.

## Design truth — three tiers, use the best available

**Tier 1 — Figma via annotations (preferred).** Read the module's
`arkive-showcase.json`. If it has a `designFileKey` and the component has a
`designNodeId`, the Figma target is already known — fetch its screenshot with the
connected Figma MCP server's screenshot tool. No URLs needed from the user.

**Tier 2 — Figma via pasted URL.** Figma MCP connected but the component has no
`designNodeId`: ask the user for the frame URL
(`figma.com/design/<fileKey>/<name>?node-id=X-Y` — **convert `X-Y` to `X:Y`** for the MCP
tool). After a successful match, **offer to backfill** `designNodeId` on the
`@ArkiveComposable`/`@ArkiveView` annotation (and `designFileKey` in the `arkive {}`
block) so every future run resolves automatically — turn the one-off URL into a permanent
code artifact.

**Tier 3 — no Figma: intent and specs.** Compare against whatever design truth exists: a
spec document, ticket acceptance criteria, or the user's stated intent in this
conversation. The same discipline applies — load the snapshot and enumerate concrete
observations against each stated requirement. If there is no articulable intent either,
ask what the screen should look like **before** judging; never invent the requirement.

## Scope rules

- **Screens first.** Compare full annotated screens by default — screens verify
  composition, spacing, and real-data context, and Figma component libraries often differ
  from code granularity. Drop to individual components only to isolate a screen-level
  discrepancy or when the user asks.
- **Base snapshots only.** Ignore variant images (filenames with a `_<category>_<value>`
  suffix, e.g. `_fontscale_large`). Variants are robustness checks with no design
  counterpart.

## The loop

1. **New screen or component? Run the reuse check first — this is a gate, not a
   suggestion.** Follow `/arkive:find` (search the catalogue + source, visually triage
   suspects) before writing any code; it returns use-it / extend-it / build-new.
   Implementing a "new" component without it is a red flag.
2. **Implement / update the view** using existing shared components (design tokens,
   typography, the project's building blocks). If nothing fits, STOP and ask before
   inventing a custom piece.
3. **Regenerate:** `./gradlew :<module>:generateShowcase<Variant>` (fastest debug
   variant). Recording is module-wide and takes minutes — iterate within one module, and
   batch fixes across a screen before regenerating rather than re-running per tweak.
4. **Locate the snapshot** in `<module>/build/generated/arkive/showcase/images/` by its
   component id (see the cheatsheet's filename convention). If it's missing, the preview
   crashed — the build log has an `Arkive: no snapshot recorded for component` warning
   (re-run with `--info` for the crash message); fix that first.
5. **Fetch the design truth** for the tier you're on.
6. **Compare in a single turn:** Read the snapshot PNG (renders visually), fetch/hold the
   design truth, and enumerate every observable difference — colors, spacing, alignment,
   font weight, corner radii, shadows, icons, missing or extra elements, text content.
   Saying "matches" or "looks close" without listed concrete observations is a rule
   violation: either list the diffs, or state specifically that none are visible. Never
   declare a match from reading your own code.
7. **Decide** (tolerance table below).

| Situation | Action |
|---|---|
| No visible diff | Done — go to the handoff |
| Visible diff, fixable with existing components | Fix, go to step 3 |
| Fix needs breaking / duplicating / customizing a shared component | **STOP. Ask.** |
| Diff is ambiguous (unclear which side is correct) | **STOP. Ask.** |
| Repeated attempts aren't converging | **STOP. Ask.** |
| Snapshot shows unstable data (current date, random values) | Fix the preview's data first — the loop needs deterministic renders |

## Handoff — when the screen matches

- If the project retains goldens (`snapshotRetention` BASE/ALL): the UI just changed
  intentionally, so the goldens are now stale — re-record (`generateShowcase<Variant>`)
  and commit the updated goldens, or CI's `verifyShowcase` will fail on this change.
- If it doesn't retain goldens yet: suggest `/arkive:snapshot-testing` to lock in the
  now-approved rendering.

## Red flags — STOP and ask

- "Close enough."
- Starting a new screen or component without the `/arkive:find` reuse check.
- "I'll build a custom version of the shared component to match the design."
- "The Figma might be out of date." (Maybe — but that's the user's call, not yours.)
- Judging a match from code inspection instead of loading both images.
- Comparing a variant image against Figma.
- Any impulse to leave a `// TODO: doesn't quite match design` comment.
Pliki w paczce (2)
  • SKILL.md 6 KB
  • references 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · infinum/arkive90Apache-2.0
jakeselby/model-citizen100MIT
jezweb/claude-skills95MIT

Migawka bazy z 13.11.2026 · wersja paczki db08f7fc7efa (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90find
    Sprawdza, czy w katalogu Arkive i w kodzie istnieje już ekran lub komponent z projektu Figma, i zwraca decyzję: użyć, rozbudować lub zbudować.
  • 90snapshot-testing
    Konfiguruje testy snapshotów z wzorcami w projekcie Arkive, diagnozuje nieudane weryfikacje i wiąże je z CI.
  • 96figma-token-sync
    Sprawdza różnice tokenów między projektem w Figmie a implementacją komponentów i je synchronizuje.
  • 90reviewing-ui
    Porównuje wdrożony interfejs z projektem w Figmie przez przechwycenie ekranu w Playwright i zwraca PASS, FAIL albo brak weryfikacji.
  • 100design-sync
    Czyta lub zapisuje źródło designu w Figmie dla agent-os: linki do zadań, migawki projektu, komentarze do węzłów i mapowania Code Connect.
  • 100figma-design-spec
    Tworzy ekrany w nowym pliku Figma na podstawie zatwierdzonego intent.md i pisze spec.md z wymaganiami i testami.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.