Omar SobhandClaude Opus 4.7
7b23f61632
Hand-authored skill catalog anchored to real 2026-07 versions:
- Rust 1.97.1 (stable), edition 2024
- React 19.2.7, Server Components + Actions
- TailwindCSS 4.3.3 (CSS-first config, Oxide engine)
- three.js r185 (WebGPURenderer stable, BatchedMesh matured)
- React Native 0.86 / Expo SDK 54+ (New Architecture default)
- cargo-nextest 0.9.140, gitleaks 8.20+, cargo-audit 0.21+
- Postgres 17 (18 in beta, don't rely on)
- CUDA Blackwell, Metal Apple7+, ROCm CDNA3
Ships 15 skills across the categories:
foundation/ workspace-repo-commit-protocol
small-focused-commits
tdd-red-green-refactor
code-review-checklist
int-xx-marker-protocol
decompose-int-items
rust/ write-rust-current-edition
rust-error-handling
cargo-test-driven-development
rust-async-tokio-idioms
backend/ postgres-migrations-forward-only
postgres-index-selection
api-pagination-day-1
frontend/ react-19-server-components
tailwind-v4-idioms
component-4-state-model
mobile/ expo-managed-vs-bare
rn-flashlist-perf
gpu/ gpu-coalescing-and-occupancy
roofline-model
threejs/ threejs-perf-and-teardown
security/ cargo-audit-workflow
secret-scanning-gitleaks
skills_loader.rs walks skills/**/*.md, parses YAML frontmatter
(name, description, when_to_use, tags), upserts via
skills_catalog::upsert_builtin. Idempotent per boot — bumps version
+ appends skill_versions row ONLY when body changes. Deterministic
sha256-derived ids so builtins are stable across boots.
Dockerfile copies skills/ to /etc/clawmates/skills. Server boot
task spawns loader alongside team_template_loader.
Follow-ups (Slice 3.5c continuation, future PRs):
- 20-30 more skills (duckdb, shadcn composition, a11y, WebGPU
migration, metal frame capture, rocprof, deep gitea forge
integration, semgrep rulepacks)
- Bind skills to team template roles (add [role.skills] refs to
templates/teams/*.toml + wire template_role_skills population
in team_template_loader)
Co-Authored-By: Claude Opus 4.7 <[email protected]>
60 lines
2.8 KiB
Markdown
60 lines
2.8 KiB
Markdown
---
|
|
name: component-4-state-model
|
|
description: Every component ships with four visual states — empty, loading, error, ready — from day 1. No spinners without skeletons.
|
|
when_to_use: You're designing or authoring a component that displays data. Frontend + mobile teams pin this.
|
|
tags: [frontend, design, ux]
|
|
---
|
|
|
|
# The four-state model
|
|
|
|
Every component that renders remote data has FOUR distinct visual states. Ship all four in the same PR — you can't "add empty state later" without shipping broken UX in the interim.
|
|
|
|
## The states
|
|
|
|
1. **Empty** — the request succeeded and returned zero items, OR the entity hasn't been created yet.
|
|
2. **Loading** — the request is in flight. Show a **skeleton** matching the eventual layout, never a spinner in isolation.
|
|
3. **Error** — the request failed. Show what went wrong + a recovery affordance (retry, contact support, or the fallback action).
|
|
4. **Ready** — data is here, render it.
|
|
|
|
## The skeleton rule
|
|
|
|
- Skeletons should match the ready state's LAYOUT within 5%. A wide card skeleton that resolves to a narrow list is disorienting.
|
|
- Skeletons pulse subtly (`animate-pulse` in Tailwind is fine). No spinners layered on top.
|
|
- Skeleton for lists shows **3 items** — enough to convey shape, not so many the eye reads them as content.
|
|
|
|
## The empty state rule
|
|
|
|
- Explain what would fill this component + the action to make it happen.
|
|
- CTA button placed prominently, not buried.
|
|
- Emojis / illustrations are fine but the copy carries the meaning.
|
|
|
|
Example (from the missions canvas):
|
|
> **No missions yet.** Pick a workflow template to get started. → `[Start a mission]`
|
|
|
|
## The error state rule
|
|
|
|
- Show the human-friendly reason (never the raw stack). "Couldn't reach the server. Retry?" not "TypeError: undefined is not a function".
|
|
- Retry button that actually retries the same request, not a page reload.
|
|
- If the error is auth (401/403), the affordance is "sign in", not "retry".
|
|
- Log the raw error to observability (Sentry, PostHog, etc.) so it's investigable. Users see the human message.
|
|
|
|
## Implementation shape (React 19)
|
|
|
|
```tsx
|
|
export function ThingList() {
|
|
const { data, error, isLoading, refetch } = useThings();
|
|
|
|
if (isLoading) return <ThingListSkeleton />;
|
|
if (error) return <ErrorCard error={error} onRetry={refetch} />;
|
|
if (!data?.length) return <EmptyCard onCreate={openWizard} />;
|
|
return <>{data.map((t) => <ThingRow key={t.id} thing={t} />)}</>;
|
|
}
|
|
```
|
|
|
|
## Anti-patterns
|
|
|
|
- **Empty state = "No data."** Do the work; explain what fills it and how.
|
|
- **Spinner-only loading state.** Nothing tells the user what's coming.
|
|
- **`data && data.length && data.map(...)`** without any branch for the falsy cases. That renders NOTHING and the user thinks the app is broken.
|
|
- **`toast.error(err.message)`** as your entire error handling. Toasts are ephemeral; a persistent error state is what tells the user the component is broken.
|