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.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- anti-slop-engineeringSkill
- anti-slop-engineeringSkill
- api-ergonomics-and-contract-governorSkill
- apple-craft-and-interaction-physicsSkill
- asset-provenance-guardSkill
- backprop-guardSkill
- chaos-and-degradation-choreographerSkill
- chromatic-drift-guardSkill
- cognitive-load-and-attention-governorSkill
- comment-budget-guardSkill
- context-window-and-token-economics-architectSkill
- cryptographic-agility-and-secret-lifecycle-gateSkill
- decision-guardSkill
- demock-guardSkill
- design-system-drift-guardSkill
- deterministic-simulation-and-property-testingSkill
- distributed-consensus-and-concurrency-gateSkill
- finops-and-unit-economics-governorSkill
- future-scale-gateSkill
- grumpy-senior-staff-engineerSkill
- honeypot-trap-guardSkill
- house-tell-guardSkill
- install-anti-slopSkill
- llm-eval-and-prompt-injection-fortressSkill
- mandela-guardSkill
- mechanical-sympathy-and-perf-gateSkill
- mechanical-sympathy-profilerSkill
- motion-runtime-guardSkill
- observability-and-slo-architectSkill
- observability-and-slo-gateSkill
- paranoid-principal-architectSkill
- pr-boundary-guardSkill
- privacy-and-data-lineage-gateSkill
- re0-handoff-guardSkill
- reduction-guardSkill
- repo-memory-and-invariant-stewardSkill
- root-fix-gateSkill
- safe-evolution-and-rollout-choreographerSkill
- scientific-fault-isolationSkill
- styleseed-guardSkill
- supply-chain-and-sbom-sentinelSkill
- tagore-guardSkill
- type-level-and-ast-slop-gateSkill
- ui-and-copy-disciplineSkill
- verification-oracle-architectSkill
- zero-downtime-migration-gateSkill
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
- Very specific: line 41
Zero Layout Thrashing: Never interleave DOM style writes and layout geometry reads (getBoundingClientRect(), offsetWidth, offsetHeight, …
- Very specific: line 43
Zero Main-Thread Blocking: Never execute large JSON.parse/JSON.stringify, synchronous localStorage/sessionStorage I/O inside …
- Very specific: line 49
Every async data boundary must render a pixel-matched skeleton or reserved grid slot whose outer dimensions (min-height, height, …
- Very specific: line 50
Every <img>, <video>, <canvas>, and <svg> must declare explicit width and height attributes or CSS aspect-ratio.
- Very specific: line 56
Epsilon-Terminated
requestAnimationFrame: Never leave continuous requestAnimationFrame loops running after spring/lerp physics settle. - Very specific: line 57
Touch Device Native Inertia: Never apply programmatic scroll hijacking or wheel-smoothing engines to touch devices.
- Very specific: line 58
Modal & Drawer Dialog Physics: All slide-out drawers, sheets, and modals must declare role="dialog" and aria-modal="true", lock …
- Very specific: line 64
Ban
transition: all: Always enumerate explicit compositor properties (transition: transform 200ms cubic-bezier(0.22, 1, 0.36, 1), opacity … - Very specific: line 65
Enforce Read-Before-Write DOM discipline: If a component must measure DOM geometry (getBoundingClientRect, offsetWidth), perform all …
- Very specific: line 69
Degrade gracefully under
partial_failure: When a composite view fetches multiple data sources (e.g., primary document + activity sidebar … - Distinctive: line 89
Before generating or approving any UI component, animation, or client state flow, interrogate the design against these five physical …
- Very specific: line 119
Runtime Physics & Falsification Verification: Verify that every state transition is deterministic, server rejection cleanly restores the …
- Distinctive: line 121
When a durable UI craft and frame-budget record is warranted, save a JSON assessment following the Frame Budget Record Contract and audit …
≈ “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.
Files
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:
- Strict 16.6ms (60Hz) / 8.3ms (120Hz ProMotion) Frame Budgets: Zero layout thrashing, GPU-compositor-only animations (
transform,opacity), epsilon-terminatedrequestAnimationFrameloops, and zero main-thread blocking Tasks (< 50msLong Task threshold,< 4msper frame script budget). - 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. - Explicit Discriminated-Union UI State Machines: Complete elimination of Boolean Soup in favor of exhaustive state machines covering
Empty,Stale,Offline,Optimistic, andPartial Failurestates.
Activation and Boundaries
| Situation | Behavior |
| Building or refactoring interactive UI views, lists, forms, or dashboards | Enforce Discriminated Union State Machines, pixel-matched skeletons (CLS = 0), and sub-50ms Optimistic UI |
| Authoring animations, transitions, drag gestures, or scroll effects | Restrict 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 streams | Offload heavy parsing/filtering/storage off the Main Thread or yield via < 4ms frame slices |
| Building slide-out drawers, sheets, dialogs, or overlays | Enforce role="dialog", aria-modal="true", body scroll lock, Tab focus trap, and focus restoration |
| Auditing frontend PRs, Lighthouse/Performance traces, or janky interactions | Run the Frame Budget & State Machine Pre-Mortem and scripts/frame_budget_guard.py |
| Headless backend workers, database DDL migrations, or CLI batch scripts | Do not activate; route to paranoid-principal-architect or zero-downtime-migration-gate |
The Five Absolute Laws
- The 16.6ms / 8.3ms Frame Budget Physics Law (60Hz / 120Hz ProMotion): On a 120Hz ProMotion display, the browser has
8.33msper frame (16.67msat 60Hz) to execute JavaScript, recalculate styles, compute layout, paint, and composite. To leave headroom for browser overhead, per-frame JavaScript work must remain under4ms.- 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 (FastDOMread phase), then batch all style mutations (requestAnimationFramewrite phase). - Compositor-Only Motion: Animate strictly
transform(translate3d,scale,rotate) andopacity. Animatingwidth,height,top,left,margin,padding, orborder-widthtriggers 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, synchronouslocalStorage/sessionStorageI/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 withscheduler.yield().
- Zero Layout Thrashing: Never interleave DOM style writes and layout geometry reads (
- The Sub-50ms Optimistic UI & Graceful Rollback Law: Human perception registers delay above
50ms–100msas 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
< 50mswhile capturing an immutable rollback snapshot (previousStateSnapshot) and attaching a deterministicIdempotency-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.
- Render physical press feedback (
- 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 explicitwidthandheightattributes or CSSaspect-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.
- Every async data boundary must render a pixel-matched skeleton or reserved grid slot whose outer dimensions (
- 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 whenisLoadingis false butdatais undefined).- Represent every view and async mutation as an explicit Discriminated Union State Machine (
statustag) with exhaustiveswitch (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, andterminal_error.
- Represent every view and async mutation as an explicit Discriminated Union State Machine (
- The Native Hardware & Accessibility Physics Law:
- Epsilon-Terminated
requestAnimationFrame: Never leave continuousrequestAnimationFrameloops running after spring/lerp physics settle. Define a strict convergence threshold ($\epsilon = 10^{-4}$) and callcancelAnimationFrame(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"andaria-modal="true", lockdocument.bodyscroll without horizontal scrollbar shift (scrollbar-gutter: stable), trapTab/Shift+Tabfocus inside the active container, and restore focus to the exact trigger element upon close (Escapeor dismiss).
- Epsilon-Terminated
Invariant Rules
- Ban
transition: all. Always enumerate explicit compositor properties (transition: transform 200ms cubic-bezier(0.22, 1, 0.36, 1), opacity 150ms ease-out).transition: allaccidentally animates layout properties (height,padding,margin) during responsive resizes and state changes. - Enforce Read-Before-Write DOM discipline. If a component must measure DOM geometry (
getBoundingClientRect,offsetWidth), perform all measurements before mutatingelement.style,classList, or DOM nodes, or isolate geometry tracking insideResizeObserver/IntersectionObservercallbacks rather thanscrollormousemovelisteners. - Passive event listeners for scroll and touch. All
scroll,wheel,touchstart, andtouchmovelisteners that do not callpreventDefault()must pass{ passive: true }so the browser compositor thread never blocks waiting on the JS main thread. - Never wipe existing screen data during background revalidation. Transitioning from
loaded_freshtorevalidating_stalemust 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. - 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.
- 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 topartial_failure: render the primary content normally and isolate the retry affordance strictly inside the failed sub-region. - Queue or guard mutations when
offline_queued. Listen tonavigator.onLine/online/offlineevents and network transport errors; transition mutations to an explicitoffline_queuedstate or disable destructive server-only actions with clear status rather than throwing unhandled promise rejections. - Enforce exhaustiveness checking (
assertNever) on UI state machines. Every view state switch statement must include adefaultbranch assigningconst _exhaustive: never = state;so TypeScript fails compilation the instant a new state variant is added without a UI renderer. - Honor
prefers-reduced-motion: reduceand44x44pxhit targets. Every interactive control must maintain at least a44x44px(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 Shape | Primary Workflow | Reference Contract |
| Auditing or fixing UI jank, frame drops, scroll stutter, or main-thread stalls | Audit Frame Budget | Compositor & Frame Budget Physics |
| Implementing instant interactions, optimistic mutations, rollback paths, and zero-CLS skeletons | Implement Optimistic & Zero-CLS UI | Optimistic UI & Zero CLS |
| Replacing Boolean Soup with exhaustive Discriminated Union State Machines | Architect UI State Machine | Discriminated Union State Machines |
| Durable frame-budget & UI craft assessment record generation & audit | Record Contract | scripts/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.3msBudget): 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 anyrequestAnimationFrameloop 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(), orlocalStorage.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
16msand the first50ms? If the server returnsHTTP 409orHTTP 500600ms 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 theloading_initialskeleton, theloaded_emptyzero-state, theloaded_freshpopulated view, and any inline error banner. Does any transition shift surrounding siblings by even1px? - The State Machine Exhaustiveness Check: Have we eliminated all loose boolean flags (
isLoading,isError,isSuccess)? How does the discriminated union explicitly renderloaded_empty,revalidating_stale,partial_failure, andoffline_queued?
Prohibited Anti-Patterns (Instant Rejection List)
- 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 unionstatusfield. - Layout Thrashing (Interleaved DOM Write -> Read): Mutating
el.style.*orclassListand subsequently readingel.offsetHeight,el.offsetWidth,el.getBoundingClientRect(), orwindow.scrollYinside a loop or synchronous frame handler. - Non-Compositor CSS Animations &
transition: all: Usingtransition: allor animatingwidth,height,top,left,right,bottom,margin, orpaddingon interactive elements. - Infinite Unterminated
requestAnimationFrameLoops: SchedulingrequestAnimationFrame(tick)unconditionally without checking whether $|\text{current} - \text{target}| < \epsilon$ (1e-4) and canceling the animation handle. - Unreserved Async Geometry (
CLS > 0): Renderingif (loading) return <Spinner />with a24pxspinner that jumps to a640pxtable on resolve, or rendering<img>tags without explicitwidth/heightoraspect-ratio. - 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. - Touch Scroll Hijacking: Running custom wheel/momentum scroll jacking on mobile/touch viewports without gating behind
!window.matchMedia('(pointer: coarse)').matches && window.innerWidth >= 768. - 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:
- 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). - Explicit Discriminated-Union State Machine Definition: Define the complete TypeScript discriminated union (
State) and event union (Event), explicitly coveringidle,loading_initial,loaded_empty,loaded_fresh,revalidating_stale,optimistic_mutating(withrollbackSnapshot),partial_failure,offline_queued, andterminal_error. - Apple-Craft Implementation (Compositor Motion + Optimistic UI + Zero-CLS): Emit clean, standards-compliant code with GPU-compositor transitions (
transform,opacity), epsilon-gatedrAFloops, touch-safe scroll gates, accessible dialog focus traps, and pixel-matched skeleton geometry. - 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.pyreports 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>] --jsonDomain 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 Mode | Observable Signal | Remediation |
| Layout thrashing jank | Frame drops (> 16.6ms) during scroll, resize, or list animation | Separate all getBoundingClientRect/offset* reads before any style/classList writes; use transform |
| Paint storm on animation | High GPU/CPU paint time while animating drawer or accordion | Replace height/left/margin transitions with transform: translate3d() / scaleY() or FLIP |
Runaway rAF battery drain | CPU stays at 15–30% when UI appears completely stationary | Add 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 loads | Reserve exact pixel dimensions via aspect-ratio, explicit width/height, and geometry-matched skeletons |
| Dead click / pessimistic lag | User clicks action button and nothing visually happens for 300ms | Add < 16ms active press transform and < 50ms optimistic state projection with rollback snapshot |
| Destructive rollback amnesia | Failed post/edit rolls back UI and deletes the text the user typed | Restore failed mutation payload directly into the draft input state on rollback |
| Boolean Soup impossible state | Spinner and error message (or empty state and data list) render at once | Refactor loose isLoading/isError booleans into a single discriminated union status switch |
| Touch scroll hijacking | Mobile Safari/Chrome scrolling feels sticky, delayed, or unnatural | Gate 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-sideIdempotency-Keydeduplication,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.
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
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.

