agentleFS
imMamdouhaboammarimMamdouhaboammar/anti-slop-engineering/skills/apple-craft-and-frame-budget/SKILL.md

apple-craft-and-frame-budget

Skill4 starsChanged 31 days agoMITView on GitHub

Enforces Apple Human Interface Guidelines (HIG) craft and 60/120Hz Client Runtime Physics across web, mobile, and desktop interfaces. Use when building, refactoring, or auditing interactive UI components, animations, state management, optimistic mutations, skeleton loaders, scroll/gesture handlers, modals, or client rendering pipelines — even if the user doesn't explicitly say "Apple craft" or "frame budget". Do NOT use for headless backend-only services, SQL schema migrations, or non-interactive CLI scripts.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 2 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

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

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

    Zero Layout Thrashing: Never interleave DOM style writes and layout geometry reads (getBoundingClientRect(), offsetWidth, offsetHeight, …

    line 41
  2. Very specific:

    Zero Main-Thread Blocking: Never execute large JSON.parse/JSON.stringify, synchronous localStorage/sessionStorage I/O inside …

    line 43
  3. Very specific:

    Every async data boundary must render a pixel-matched skeleton or reserved grid slot whose outer dimensions (min-height, height, …

    line 49
  4. Very specific:

    Every <img>, <video>, <canvas>, and <svg> must declare explicit width and height attributes or CSS aspect-ratio.

    line 50
  5. Very specific:

    Epsilon-Terminated requestAnimationFrame: Never leave continuous requestAnimationFrame loops running after spring/lerp physics settle.

    line 56
  6. Very specific:

    Touch Device Native Inertia: Never apply programmatic scroll hijacking or wheel-smoothing engines to touch devices.

    line 57
  7. Very specific:

    Modal & Drawer Dialog Physics: All slide-out drawers, sheets, and modals must declare role="dialog" and aria-modal="true", lock …

    line 58
  8. Very specific:

    Ban transition: all: Always enumerate explicit compositor properties (transition: transform 200ms cubic-bezier(0.22, 1, 0.36, 1), opacity …

    line 64
  9. Very specific:

    Enforce Read-Before-Write DOM discipline: If a component must measure DOM geometry (getBoundingClientRect, offsetWidth), perform all …

    line 65
  10. Very specific:

    Degrade gracefully under partial_failure: When a composite view fetches multiple data sources (e.g., primary document + activity sidebar …

    line 69
  11. Distinctive:

    Before generating or approving any UI component, animation, or client state flow, interrogate the design against these five physical …

    line 89
  12. Very specific:

    Runtime Physics & Falsification Verification: Verify that every state transition is deterministic, server rejection cleanly restores the …

    line 119
  13. Distinctive:

    When a durable UI craft and frame-budget record is warranted, save a JSON assessment following the Frame Budget Record Contract and audit …

    line 121

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Skill: Apple Craft & Frame Budget (Apple HIG & 60/120Hz Client Runtime Physics)

Anti-slop UI rules stop an interface from looking broken; Apple runtime physics make an interface feel alive, instantaneous, and physically Inevitable at 120Hz.

Why This Skill Is Needed & Target State

Baseline UI hygiene in anti-slop-engineering prevents visual slop—stripping developer notes from the DOM, decluttering navbars, and banning patronizing microcopy. However, an interface can be visually clean and still feel sluggish, fragile, and amateurish in motion. AI coding agents routinely generate UI components that trigger forced synchronous reflows (Layout Thrashing), animate layout properties (height, top, left), freeze the main thread with synchronous JSON.parse/localStorage calls, block user clicks behind network spinners, shift layout geometry as payloads resolve (CLS > 0), and collapse into impossible states due to combinatorial "Boolean Soup" (isLoading && !isError && isSubmitted).

The target state is Apple Human Interface Guidelines (HIG) Craft & 60/120Hz Client Runtime Physics:

  1. Strict 16.6ms (60Hz) / 8.3ms (120Hz ProMotion) Frame Budgets: Zero layout thrashing, GPU-compositor-only animations (transform, opacity), epsilon-terminated requestAnimationFrame loops, and zero main-thread blocking Tasks (< 50ms Long Task threshold, < 4ms per frame script budget).
  2. Sub-50ms Optimistic UI & Zero Cumulative Layout Shift (CLS = 0.000): Instantaneous visual acknowledgment on every interaction with deterministic rollback snapshots on server failure, paired with pixel-exact skeleton and media geometry reservation.
  3. Explicit Discriminated-Union UI State Machines: Complete elimination of Boolean Soup in favor of exhaustive state machines covering Empty, Stale, Offline, Optimistic, and Partial Failure states.

Activation and Boundaries

SituationBehavior
Building or refactoring interactive UI views, lists, forms, or dashboardsEnforce Discriminated Union State Machines, pixel-matched skeletons (CLS = 0), and sub-50ms Optimistic UI
Authoring animations, transitions, drag gestures, or scroll effectsRestrict to compositor properties (transform, opacity), enforce epsilon-terminated rAF, and gate scroll hijacking off touch devices
Handling large client datasets, local persistence, or real-time streamsOffload heavy parsing/filtering/storage off the Main Thread or yield via < 4ms frame slices
Building slide-out drawers, sheets, dialogs, or overlaysEnforce role="dialog", aria-modal="true", body scroll lock, Tab focus trap, and focus restoration
Auditing frontend PRs, Lighthouse/Performance traces, or janky interactionsRun the Frame Budget & State Machine Pre-Mortem and scripts/frame_budget_guard.py
Headless backend workers, database DDL migrations, or CLI batch scriptsDo not activate; route to paranoid-principal-architect or zero-downtime-migration-gate

The Five Absolute Laws

  1. The 16.6ms / 8.3ms Frame Budget Physics Law (60Hz / 120Hz ProMotion): On a 120Hz ProMotion display, the browser has 8.33ms per frame (16.67ms at 60Hz) to execute JavaScript, recalculate styles, compute layout, paint, and composite. To leave headroom for browser overhead, per-frame JavaScript work must remain under 4ms.
    • Zero Layout Thrashing: Never interleave DOM style writes and layout geometry reads (getBoundingClientRect(), offsetWidth, offsetHeight, clientHeight, scrollTop, getComputedStyle()) within the same frame. Batch all geometry reads first (FastDOM read phase), then batch all style mutations (requestAnimationFrame write phase).
    • Compositor-Only Motion: Animate strictly transform (translate3d, scale, rotate) and opacity. Animating width, height, top, left, margin, padding, or border-width triggers full document reflow and paint on every frame and is strictly prohibited. Use FLIP (First, Last, Invert, Play) for layout transitions.
    • Zero Main-Thread Blocking: Never execute large JSON.parse/JSON.stringify, synchronous localStorage/sessionStorage I/O inside render/scroll/input paths, or $O(N)$ sorting/filtering over $>500$ items on the Main Thread. Offload to Web Workers, IndexedDB async transactions, or chunk work across frames with scheduler.yield().
  2. The Sub-50ms Optimistic UI & Graceful Rollback Law: Human perception registers delay above 50ms–100ms as mechanical lag. Every discrete user action (button press, toggle, reorder, like, archive, inline edit) must:
    • Render physical press feedback (transform: scale(0.97) or active highlight) within < 16ms (1 frame).
    • Transition the UI state optimistically within < 50ms while capturing an immutable rollback snapshot (previousStateSnapshot) and attaching a deterministic Idempotency-Key.
    • Execute a smooth, non-destructive Rollback Transition that restores previousStateSnapshot, preserves any user-typed draft input, and surfaces an actionable inline recovery state (Retry / Dismiss) if the server rejects or times out.
  3. The Zero Cumulative Layout Shift Law (CLS = 0.000): Content must never jump, shift, or push interactive targets while asynchronous data, images, or web fonts stream in.
    • Every async data boundary must render a pixel-matched skeleton or reserved grid slot whose outer dimensions (min-height, height, aspect-ratio, padding, border) identically match the resolved state.
    • Every <img>, <video>, <canvas>, and <svg> must declare explicit width and height attributes or CSS aspect-ratio.
    • Stale-while-revalidate refreshes and inline validation errors must overlay or occupy pre-allocated layout tracks—never injecting unreserved DOM banners that push the document down.
  4. The Explicit State Machine Law (Zero Boolean Soup): Combinatorial boolean flags (const [isLoading, setIsLoading] = useState(false); const [isError, setIsError] = useState(false); const [isSubmitted, setIsSubmitted] = useState(false);) create $2^N$ implicit states, inevitably producing impossible UI states (e.g., spinner and error banner visible simultaneously, or blank white screens when isLoading is false but data is undefined).
    • Represent every view and async mutation as an explicit Discriminated Union State Machine (status tag) with exhaustive switch (state.status) rendering.
    • Explicitly model and design all real-world operational states: idle, loading_initial, loaded_empty, loaded_fresh, revalidating_stale, optimistic_mutating, partial_failure, offline_queued, and terminal_error.
  5. The Native Hardware & Accessibility Physics Law:
    • Epsilon-Terminated requestAnimationFrame: Never leave continuous requestAnimationFrame loops running after spring/lerp physics settle. Define a strict convergence threshold ($\epsilon = 10^{-4}$) and call cancelAnimationFrame(handle) as soon as $|\text{current} - \text{target}| < \epsilon$ and $|\text{velocity}| < \epsilon$.
    • Touch Device Native Inertia: Never apply programmatic scroll hijacking or wheel-smoothing engines to touch devices. Gate all custom momentum scroll engines behind !window.matchMedia('(pointer: coarse)').matches && window.innerWidth >= 768.
    • Modal & Drawer Dialog Physics: All slide-out drawers, sheets, and modals must declare role="dialog" and aria-modal="true", lock document.body scroll without horizontal scrollbar shift (scrollbar-gutter: stable), trap Tab / Shift+Tab focus inside the active container, and restore focus to the exact trigger element upon close (Escape or dismiss).

Invariant Rules

  1. Ban transition: all. Always enumerate explicit compositor properties (transition: transform 200ms cubic-bezier(0.22, 1, 0.36, 1), opacity 150ms ease-out). transition: all accidentally animates layout properties (height, padding, margin) during responsive resizes and state changes.
  2. Enforce Read-Before-Write DOM discipline. If a component must measure DOM geometry (getBoundingClientRect, offsetWidth), perform all measurements before mutating element.style, classList, or DOM nodes, or isolate geometry tracking inside ResizeObserver / IntersectionObserver callbacks rather than scroll or mousemove listeners.
  3. Passive event listeners for scroll and touch. All scroll, wheel, touchstart, and touchmove listeners that do not call preventDefault() must pass { passive: true } so the browser compositor thread never blocks waiting on the JS main thread.
  4. Never wipe existing screen data during background revalidation. Transitioning from loaded_fresh to revalidating_stale must keep the existing data interactive on screen while showing a subtle, non-blocking refresh indicator—never replacing already-loaded content with a full-screen spinner or skeleton.
  5. Preserve user drafts across optimistic rollbacks and network failures. If a form submission or comment post fails, rolling back the optimistic item must restore the user's exact input text back into the composer field so zero keystrokes are lost.
  6. Degrade gracefully under partial_failure. When a composite view fetches multiple data sources (e.g., primary document + activity sidebar + recommendations) and a secondary source fails, transition to partial_failure: render the primary content normally and isolate the retry affordance strictly inside the failed sub-region.
  7. Queue or guard mutations when offline_queued. Listen to navigator.onLine / online / offline events and network transport errors; transition mutations to an explicit offline_queued state or disable destructive server-only actions with clear status rather than throwing unhandled promise rejections.
  8. Enforce exhaustiveness checking (assertNever) on UI state machines. Every view state switch statement must include a default branch assigning const _exhaustive: never = state; so TypeScript fails compilation the instant a new state variant is added without a UI renderer.
  9. Honor prefers-reduced-motion: reduce and 44x44px hit targets. Every interactive control must maintain at least a 44x44px (2.75rem) touch target area, and all spatial spring/slide animations must degrade to instant or opacity-only cross-fades when @media (prefers-reduced-motion: reduce) is active.

Execution Router

Task ShapePrimary WorkflowReference Contract
Auditing or fixing UI jank, frame drops, scroll stutter, or main-thread stallsAudit Frame BudgetCompositor & Frame Budget Physics
Implementing instant interactions, optimistic mutations, rollback paths, and zero-CLS skeletonsImplement Optimistic & Zero-CLS UIOptimistic UI & Zero CLS
Replacing Boolean Soup with exhaustive Discriminated Union State MachinesArchitect UI State MachineDiscriminated Union State Machines
Durable frame-budget & UI craft assessment record generation & auditRecord Contractscripts/frame_budget_guard.py

Mandatory Pre-Render Interrogation Matrix

Before generating or approving any UI component, animation, or client state flow, interrogate the design against these five physical constraints:

  • The 120Hz Compositor Check (8.3ms Budget): Does this interaction read any layout metric (offsetWidth, getBoundingClientRect, scrollTop) after mutating the DOM? Does any CSS transition touch a non-compositor property (height, width, top, left, margin, filter: blur() without layer bounds)? Does any requestAnimationFrame loop lack an epsilon ($\epsilon = 10^{-4}$) termination check?
  • The Main-Thread Stall Check: What happens if the payload contains 5,000 rows or a 2MB JSON blob? Are we running .filter().sort(), JSON.parse(), or localStorage.setItem() synchronously during user input or scroll frames instead of debouncing, virtualizing, or offloading to a Web Worker?
  • The Sub-50ms Optimistic & Rollback Check: When the user clicks this button on a 400ms 3G connection, what happens in the first 16ms and the first 50ms? If the server returns HTTP 409 or HTTP 500 600ms later, do we have the exact prior state snapshot to roll back cleanly without losing the user's draft input?
  • The Zero-CLS Geometry Check (CLS = 0.000): Compare the bounding-box height and width of the loading_initial skeleton, the loaded_empty zero-state, the loaded_fresh populated view, and any inline error banner. Does any transition shift surrounding siblings by even 1px?
  • The State Machine Exhaustiveness Check: Have we eliminated all loose boolean flags (isLoading, isError, isSuccess)? How does the discriminated union explicitly render loaded_empty, revalidating_stale, partial_failure, and offline_queued?

Prohibited Anti-Patterns (Instant Rejection List)

  1. Boolean Soup State Modeling: Using 2 or more independent boolean state flags (isLoading, isError, isSuccess, isFetching, isSubmitted) to control view rendering instead of a discriminated union status field.
  2. Layout Thrashing (Interleaved DOM Write -> Read): Mutating el.style.* or classList and subsequently reading el.offsetHeight, el.offsetWidth, el.getBoundingClientRect(), or window.scrollY inside a loop or synchronous frame handler.
  3. Non-Compositor CSS Animations & transition: all: Using transition: all or animating width, height, top, left, right, bottom, margin, or padding on interactive elements.
  4. Infinite Unterminated requestAnimationFrame Loops: Scheduling requestAnimationFrame(tick) unconditionally without checking whether $|\text{current} - \text{target}| < \epsilon$ (1e-4) and canceling the animation handle.
  5. Unreserved Async Geometry (CLS > 0): Rendering if (loading) return <Spinner /> with a 24px spinner that jumps to a 640px table on resolve, or rendering <img> tags without explicit width/height or aspect-ratio.
  6. Pessimistic Blocking Mutations Without Rollback: Freezing a form or toggle behind a blocking spinner for a routine mutation without optimistic projection, or mutating optimistic state without storing a rollback snapshot (previousSnapshot) for error recovery.
  7. Touch Scroll Hijacking: Running custom wheel/momentum scroll jacking on mobile/touch viewports without gating behind !window.matchMedia('(pointer: coarse)').matches && window.innerWidth >= 768.
  8. Inaccessible Modals/Drawers: Rendering custom modals or slide-over drawers lacking role="dialog", aria-modal="true", body scroll lock, Tab focus trapping, or focus return on close.

Required Output & Review Workflow

Structure all UI architecture designs, component implementations, and frontend performance reviews through this 4-phase discipline:

  1. Frame-Budget & CLS Pre-Mortem: Audit the target interaction against the 8.3ms (120Hz) / 16.6ms (60Hz) frame budget, identifying potential layout-thrashing read/write cycles, main-thread blocking calls, and layout shift vectors (CLS).
  2. Explicit Discriminated-Union State Machine Definition: Define the complete TypeScript discriminated union (State) and event union (Event), explicitly covering idle, loading_initial, loaded_empty, loaded_fresh, revalidating_stale, optimistic_mutating (with rollbackSnapshot), partial_failure, offline_queued, and terminal_error.
  3. Apple-Craft Implementation (Compositor Motion + Optimistic UI + Zero-CLS): Emit clean, standards-compliant code with GPU-compositor transitions (transform, opacity), epsilon-gated rAF loops, touch-safe scroll gates, accessible dialog focus traps, and pixel-matched skeleton geometry.
  4. Runtime Physics & Falsification Verification: Verify that every state transition is deterministic, server rejection cleanly restores the rollback snapshot without data loss, exhaustive switch checking holds, and scripts/frame_budget_guard.py reports zero findings.

When a durable UI craft and frame-budget record is warranted, save a JSON assessment following the Frame Budget Record Contract and audit it with:

npx anti-slop-engineering frame-budget audit <record.json> --json
# or: python3 scripts/frame_budget_guard.py audit <record.json> [--source <component.tsx>] --json

Domain References

  • Apple Craft & Frame Budget Playbook Suite: Central orchestration index for 60/120Hz runtime physics, optimistic UI, and state-machine architecture.
  • 60/120Hz Frame Budget & Compositor Physics Playbook: Browser rendering pipeline mechanics, FastDOM read/write batching, FLIP layout animations, epsilon-terminated springs, touch inertia gates, and Web Worker offloading.
  • Optimistic UI, Zero-CLS & Discriminated State Machines Playbook: Sub-50ms optimistic mutations, rollback snapshot choreography, pixel-exact skeleton reservation, and exhaustive union reducers.
  • Compositor & Frame Budget Reference: Exact 16.6ms/8.3ms budget breakdowns, DOM properties that trigger layout/paint vs compositor, and main-thread time-slicing patterns.
  • Optimistic UI & Zero-CLS Reference: Snapshot-mutate-reconcile-rollback patterns, idempotency keys, skeleton geometry parity, and font/image CLS locks.
  • Discriminated Union State Machines Reference: TypeScript state machine templates replacing Boolean Soup across data fetching, forms, offline queues, and partial failures.
  • Frame Budget Record Contract: JSON schema and verification rules for scripts/frame_budget_guard.py.

Failure Taxonomy

Failure ModeObservable SignalRemediation
Layout thrashing jankFrame drops (> 16.6ms) during scroll, resize, or list animationSeparate all getBoundingClientRect/offset* reads before any style/classList writes; use transform
Paint storm on animationHigh GPU/CPU paint time while animating drawer or accordionReplace height/left/margin transitions with transform: translate3d() / scaleY() or FLIP
Runaway rAF battery drainCPU stays at 15–30% when UI appears completely stationaryAdd epsilon convergence check (Math.abs(target - current) < 1e-4) and call cancelAnimationFrame
Jarring screen jump (CLS > 0)Buttons or text jump downward when API response or image loadsReserve exact pixel dimensions via aspect-ratio, explicit width/height, and geometry-matched skeletons
Dead click / pessimistic lagUser clicks action button and nothing visually happens for 300msAdd < 16ms active press transform and < 50ms optimistic state projection with rollback snapshot
Destructive rollback amnesiaFailed post/edit rolls back UI and deletes the text the user typedRestore failed mutation payload directly into the draft input state on rollback
Boolean Soup impossible stateSpinner and error message (or empty state and data list) render at onceRefactor loose isLoading/isError booleans into a single discriminated union status switch
Touch scroll hijackingMobile Safari/Chrome scrolling feels sticky, delayed, or unnaturalGate custom smooth-scroll engines behind !window.matchMedia('(pointer: coarse)').matches && window.innerWidth >= 768

Delegated Skills

  • anti-slop-engineering: Enforce parent UI hygiene (zero dev-notes leakage in DOM, visual restraint, zero patronizing microcopy, and Direct Payload Invariant).
  • paranoid-principal-architect: Pair optimistic UI mutations with server-side Idempotency-Key deduplication, AbortSignal.timeout(), and data-layer authorization checks.
  • scientific-fault-isolation: Use deterministic barrier latches and virtualized clocks when testing out-of-order optimistic mutation responses and race rollbacks.

Completion and Limits

The task is complete when all animations and frame loops respect the 16.6ms/8.3ms compositor budget without layout thrashing, continuous rAF loops terminate at epsilon (1e-4), touch devices retain native scroll inertia, modals enforce dialog ARIA and focus physics, interactive mutations provide sub-50ms optimistic feedback with verified rollback snapshots, async boundaries reserve exact pixel geometry (CLS = 0.000), and UI state is modeled as an exhaustive discriminated union with zero Boolean Soup. A review may validly output refuse or pause if a proposed UI implementation relies on layout-thrashing animations, unreserved layout shifts, or unguarded boolean state flags.

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.