@mohammadhprp/system-prompt 0.12.2 → 0.12.4

package/framework/skills/great-interface/references/forms.md

@@ -1,84 +0,0 @@
-# Forms
-
-Labels, autocomplete, error messaging, input types and submit behavior.
-
-## Labels
-
-Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label. It disappears the moment the user types and usually fails contrast.
-
-```html
-<!-- Good: explicit association -->
-<label for="email">Email</label>
-<input id="email" type="email" autocomplete="email" />
-
-<!-- Good: wrapping label, so label and control share one hit target -->
-<label>
-  <input type="checkbox" /> Send me updates
-</label>
-```
-
-Label and control share one hit target, so clicking "Send me updates" toggles the checkbox with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
-
-A placeholder used *in addition to* a label shows an example of the expected format: `placeholder="name@company.com"`.
-
-## Error messaging
-
-The complete pattern:
-
-```html
-<label for="email">Email</label>
-<input
-  id="email"
-  type="email"
-  autocomplete="email"
-  aria-invalid="true"
-  aria-describedby="email-error"
-/>
-<p id="email-error">Enter a valid email address.</p>
-```
-
-- `aria-invalid="true"` on the failing field, removed once fixed.
-- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
-- Errors render inline beside their fields, with an icon or text. Never a red border alone, which is a color-only cue.
-- On submit, focus the first invalid field.
-- Allow incomplete submission so validation can surface. Never disable submit until valid (see below).
-- Accept free text and validate after. Never block typing or filter characters as the user types. Trim values before validating, because autocomplete and text expansion add trailing spaces.
-
-## Autocomplete and input types
-
-`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
-
-| Field | `autocomplete` |
-| --- | --- |
-| Name | `name` (or `given-name` / `family-name`) |
-| Email | `email` |
-| Phone | `tel` |
-| Address | `street-address`, `address-line1`, `postal-code`, `country` |
-| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
-| Login | `username`, `current-password` |
-| Signup / reset | `new-password` |
-| 2FA code | `one-time-code` |
-
-Prefix with a section where relevant: `autocomplete="shipping street-address"`.
-
-Correct `type` and `inputmode` pick the right mobile keyboard:
-
-| Input | Use |
-| --- | --- |
-| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
-| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
-| Money, decimals | `type="text" inputmode="decimal"` |
-| True numeric quantity | `type="number"` |
-
-Disable spellcheck on emails, codes and usernames: `spellcheck="false"`.
-
-## Never fight the user's tools
-
-- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
-
-## Submit behavior
-
-- Keep submit enabled until the request starts, then disable it and show a spinner *beside the original label*. "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
-- Announce results. Success goes through a polite live region. On failure, focus the first invalid field, which is itself the announcement. Reserve `role="alert"` for form-level errors not tied to a field ([screen-readers.md](screen-readers.md)).
-- Warn on unsaved changes before navigation, and never lose typed input to a re-render. Hydration must preserve focus and value.
-- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.

package/framework/skills/great-interface/references/from-an-image.md

@@ -1,55 +0,0 @@
-# Reading a screenshot
-
-The method for a screenshot, where the answer is a reconstruction rather than a reading. Which property lands in which bucket:
-
-| Exact from pixels | Ratios only | Unavailable |
-| --- | --- | --- |
-| Color values | Type sizes | Tokens and their names |
-| Contrast between any two sampled colors | Spacing values | The stack and styling system |
-| Relative proportion of anything measurable | Radii | Breakpoints |
-| Which colors repeat and where | Stroke and border weights | Motion, easing, duration |
-| | | Every state but the captured one |
-
-You do not know the capture's scale. A screenshot may be at 1×, 2×, or browser zoom, so a measured 30px could be 15pt of type or 30. Never report a `px` size or spacing from an image alone.
-
-One exception. Where the image contains text you can identify as body copy, assume `16px` and express everything as a multiple of it. Say you did, since the assumption may be wrong.
-
-## Colors, which are the reliable part
-
-Sample the actual pixels rather than describing what you see. Then hand the values to `better-colors`:
-
-- Convert each to OKLCH, so lightness is comparable across hues.
-- Sort by lightness to see whether the samples form a ramp and whether steps sit denser at the light end.
-- Check hue constancy across the ramp. A drifting hue means someone picked the ramp by eye.
-- Measure contrast on every foreground and background pair you can isolate. It is exact and the most valuable single number an image gives you.
-- Watch for a tinted neutral. A gray carrying a few percent of the accent hue is a deliberate choice worth naming.
-
-## Type, by category not by name
-
-You cannot identify a typeface from a screenshot with confidence, so never claim one. You can read its category and features, which is what transfers:
-
-- **Category:** geometric sans, grotesque, humanist, transitional serif, slab. Say which and why.
-- **Tells worth naming:** single or double-storey `a` and `g`, terminal angle, aperture, x-height against cap height. Also whether the digits are lining or old-style and whether the figures look tabular.
-- **Scale:** count the distinct sizes. Express them as multiples of the body size and derive the ratio.
-- **Weight contrast:** how many weights and how far apart. Two weights three steps apart reads deliberate, four weights one step apart accidental.
-- **Measure:** count characters on a full line of body copy and compare against `better-typography`'s 60 to 75 range.
-
-Where the actual face matters, name the category and suggest identifying it from the live page.
-
-## Spacing, as a rhythm
-
-Measure in the image, then divide everything by the smallest repeated gap. That quotient set is the rhythm, and it survives not knowing the scale.
-
-Then check the ratio `better-layout` owns, the gap between groups against the gap within one. At or above 2, space is carrying the grouping. Below that, something else is, usually a border or a background shape.
-
-## Say what the image hid
-
-Close by naming what a screenshot could not show, since that is where the reader would otherwise assume you looked:
-
-- Hover, focus, active, disabled, loading, empty and error states.
-- Whether anything animates and how.
-- Behavior at any other width.
-- Whether it is keyboard reachable and whether focus is visible.
-- The other appearance, light or dark.
-
-Where any of these matter to the reader's question, say that a live URL would answer it and this image cannot.

package/framework/skills/great-interface/references/grouping-and-alignment.md

@@ -1,123 +0,0 @@
-# Grouping and alignment
-
-How spacing, shapes, shared edges and ordering communicate what belongs together and what matters most.
-
-## Group with space, not lines
-
-Three tools create grouping, in order of preference:
-
-1. **Negative space**, the default. Related items sit close, unrelated ones far apart.
-2. **Background shapes**, a card or filled container, where a group must read as one unit such as a selectable row or a draggable card.
-3. **Separator lines**, a last resort for dense data where space costs too much, such as tables and long settings lists.
-
-The structural rule is that the gap between groups is at least 2× the gap within one. At `8px` inside a group, groups need `16px`+ between them, or the eye can't tell where one ends.
-
-```css
-/* Good: spacing alone communicates the grouping */
-.field-group { display: flex; flex-direction: column; gap: 8px; }
-.form { display: flex; flex-direction: column; gap: 24px; }
-
-/* Bad: uniform spacing plus lines to compensate */
-.form > * { margin-bottom: 12px; border-bottom: 1px solid var(--separator); }
-```
-
-```html
-<!-- Good: Tailwind -->
-<div class="space-y-6">
-  <div class="space-y-2">…field group…</div>
-  <div class="space-y-2">…field group…</div>
-</div>
-```
-
-Where a separator is genuinely needed, keep it quiet: hairline width, low contrast, never combined with a large gap that already did the job.
-
-## Keep controls distinct from content
-
-Interactive elements need a visual signal: a background, a border, an underline, or placement in a consistent control zone such as a toolbar or footer row. A control styled identically to static text is invisible.
-
-```html
-<!-- Bad: action looks exactly like the description text next to it -->
-<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
-
-<!-- Good: the action reads as an action -->
-<p class="text-zinc-600">Your trial ends soon.</p>
-<button class="font-medium text-blue-600">Upgrade now</button>
-```
-
-The inverse holds too. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
-
-## Align to shared edges
-
-Pick a small set of alignment edges and put everything on them, because the eye tracks straight edges to scan content.
-
-- Every stray edge reads as noise even when nobody can name it: an icon 2px off the text edge, a card padded unlike its neighbor.
-- Use one project spacing step to express hierarchy. `16px` is a useful default where no scale exists, and deeper nesting repeats the same step.
-- Numbers in tables align to the trailing edge, text to the leading edge. Tabular figures are `better-typography`'s.
-
-```css
-/* Good: one shared leading edge, one indent step */
-.section { padding-inline: 24px; }
-.section .child { margin-inline-start: 16px; }
-
-/* Bad: three unrelated leading edges in one column */
-.header { padding-inline-start: 20px; }
-.list-item { padding-inline-start: 14px; }
-.footer { padding-inline-start: 24px; }
-```
-
-## Logical properties, not physical
-
-Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
-
-| Physical (avoid) | Logical (use) |
-| --- | --- |
-| `margin-left` | `margin-inline-start` |
-| `padding-right` | `padding-inline-end` |
-| `left: 0` | `inset-inline-start: 0` |
-| `text-align: left` | `text-align: start` |
-| `border-right` | `border-inline-end` |
-
-```html
-<!-- Good: Tailwind logical utilities -->
-<div class="ms-4 pe-6 text-start">…</div>
-
-<!-- Bad: breaks in RTL -->
-<div class="ml-4 pr-6 text-left">…</div>
-```
-
-Reserve physical properties for things that refer to physical screen sides whatever the language, such as positioning against a device notch or matching a gesture direction.
-
-Where arrangement encodes progression, as in star ratings, step indicators and progress bars, the sequence mirrors in RTL and stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements do not. Digit order inside numbers never reverses, which with other bidi rules belongs to `better-typography`.
-
-## Order by importance
-
-Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
-
-- The most important information sits near the top and the leading edge. The further down and trailing something sits, the less attention it gets.
-- Give essential information room. Never bury the one number the user came for under rows of secondary detail. Push that into collapsed sections, tabs, or detail views.
-- Within a row, identifying content leads and metadata and actions trail.
-
-```html
-<!-- Good: primary fact first, detail demoted -->
-<div>
-  <p class="text-2xl font-semibold">$4,320.00</p>
-  <p class="text-sm text-zinc-500">Available balance</p>
-</div>
-
-<!-- Bad: the key fact is buried below the fold of the card -->
-<div>
-  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
-  <p class="text-sm">Last statement: June 30</p>
-  <p class="text-sm">Balance: $4,320.00</p>
-</div>
-```
-
-With logical properties, the same hierarchy mirrors correctly in RTL locales.
-
-## Don't overload the entry point
-
-The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
-
-- One primary action per view. `better-colors` owns how color enforces it.
-- Group secondary actions behind a menu once they exceed two or three.
-- Prefer a short view that links deeper over a long view that shows everything at level one.

package/framework/skills/great-interface/references/hit-areas.md

@@ -1,94 +0,0 @@
-# Hit areas
-
-Target sizes, expanding hit areas without changing visual size and collision rules.
-
-## Target sizes
-
-Separate the conformance baseline from larger usability targets:
-
-| Standard | Minimum |
-| --- | --- |
-| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
-| WCAG 2.5.5 (AAA) | 44×44px |
-| Apple HIG | 44×44pt |
-| Material Design | 48×48dp |
-
-WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its exceptions. Treat 44px as the recommended touch target for primary controls and 40px as a useful desktop target where density permits. Smaller controls are not automatic failures. Check the spacing, equivalent-control, inline, user-agent and essential exceptions before reporting one.
-
-Under the spacing exception, an undersized target passes when a 24px circle centered on its bounding box intersects no other target and no other undersized target's circle. In the simple case, 20px targets need a 4px gap.
-
-The visible element can stay small; the hit area is what must be big. Anything that looks clickable must be clickable across its whole visual extent, with no dead zones. A checkbox and its label share one hit target.
-
-## Expanding the hit area
-
-Where the visible element is smaller, say a 20×20 checkbox, extend the hit area with a pseudo-element. Put it on the wrapping `<label>` or `<button>`, never on the `<input>`, because replaced elements don't render `::before`/`::after` reliably.
-
-### CSS example
-
-```css
-/* Small checkbox with expanded 44px hit area, on the wrapping label */
-.checkbox-label {
-  position: relative;
-  width: 20px;
-  height: 20px;
-}
-
-.checkbox-label::after {
-  content: "";
-  position: absolute;
-  top: 50%;
-  left: 50%; /* physical centering: direction-independent */
-  transform: translate(-50%, -50%);
-  width: 44px;
-  height: 44px;
-}
-```
-
-### Tailwind example
-
-```tsx
-<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
-  <CheckIcon />
-</button>
-```
-
-### Layout alternative
-
-Where the element can afford real box size, skip the pseudo-element and let the box be the target. That hands the browser real geometry for scrolling and gestures:
-
-```css
-.icon-button {
-  min-width: 44px;
-  min-height: 44px;
-  display: inline-grid;
-  place-items: center;
-}
-```
-
-## Collision rule
-
-Where the extended hit area overlaps another interactive element, shrink the pseudo-element to the largest size that does not collide. Two interactive elements never have overlapping hit areas.
-
-## Decorative layers
-
-A decorative layer painted over interactive content absorbs every pointer event its box covers: a gradient scrim, a glow, a blurred sheen, a full-bleed `::after`. The control underneath looks live and does nothing, and no hit-area sizing fixes it.
-
-Give each one `pointer-events: none` (Tailwind `pointer-events-none`) so events reach the control below, plus `aria-hidden="true"` to keep it out of the accessibility tree:
-
-```css
-.card-glow {
-  position: absolute;
-  inset: 0;
-  pointer-events: none;
-}
-```
-
-Keep pointer events on any layer the user is meant to hit: a modal scrim that dismisses on click is a control, not decoration.
-
-## Touch behavior
-
-- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
-- Set `touch-action: none` on a surface implementing its own pan, zoom, or drag gestures, so the browser stops claiming them for scrolling and pinch-zoom. Scope it to that surface; at page level it removes scrolling.
-- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
-- Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and holds until the user taps elsewhere, so it reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under this query.
-- Prefer generous targets and clear affordances over finicky interactions such as tiny drag handles and precise hover zones.

package/framework/skills/great-interface/references/icon-transitions.md

@@ -1,102 +0,0 @@
-# Icon transitions
-
-Cross-fading an icon when it changes contextually or by state, with and without a motion library. Icon weight, color and direction live in [icons.md](icons.md).
-
-## Contextual icon animations
-
-When icons appear or disappear contextually, on hover or a state change, animate them with `opacity`, `scale` and `blur` rather than toggling visibility.
-
-### Motion example
-
-This uses the `motion` package. Where the project has `framer-motion`, import the same APIs from `"framer-motion"`. Never mix an installed package with the other's import path.
-
-```tsx
-import { AnimatePresence, motion } from "motion/react";
-
-function IconButton({ isActive, icon: Icon }) {
-  return (
-    <button>
-      <AnimatePresence mode="popLayout">
-        <motion.span
-          key={isActive ? "active" : "inactive"}
-          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
-          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
-          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
-        >
-          <Icon />
-        </motion.span>
-      </AnimatePresence>
-    </button>
-  );
-}
-```
-
-### CSS transition approach (no Motion)
-
-Without Motion or Framer Motion, keep both icons in the DOM and cross-fade with CSS transitions. Neither unmounts, so enter and exit both animate smoothly.
-
-One icon is absolutely positioned on top of the other. Toggling state cross-fades them, the entering icon scaling up from `0.25` while the exiting one scales down to `0.25`, both with opacity and blur.
-
-```tsx
-function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
-  return (
-    <button>
-      <div className="relative">
-        <div
-          className={cn(
-            "absolute inset-0 flex items-center justify-center",
-            "transition-[opacity,filter,scale] duration-300",
-            "ease-[cubic-bezier(0.2,0,0,1)]",
-            isActive
-              ? "scale-100 opacity-100 blur-0"
-              : "scale-[0.25] opacity-0 blur-[4px]"
-          )}
-        >
-          <ActiveIcon />
-        </div>
-        <div
-          className={cn(
-            "transition-[opacity,filter,scale] duration-300",
-            "ease-[cubic-bezier(0.2,0,0,1)]",
-            isActive
-              ? "scale-[0.25] opacity-0 blur-[4px]"
-              : "scale-100 opacity-100 blur-0"
-          )}
-        >
-          <InactiveIcon />
-        </div>
-      </div>
-    </button>
-  );
-}
-```
-
-The non-absolute icon, `InactiveIcon`, defines the layout size. The absolute one, `ActiveIcon`, overlays it without affecting flow.
-
-### Choosing between Motion and CSS
-
-| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
-| --- | --- | --- |
-| **Enter animation** | Yes | Yes |
-| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
-| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
-| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
-
-Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or `"framer-motion"` when that is. Where both exist, follow the imports the component or its nearest peers already use. Where neither is present, use the CSS cross-fade and never add a dependency just for icon transitions.
-
-### When to animate icons
-
-| Animate | Don't animate |
-| --- | --- |
-| Icons that appear on hover (action buttons) | Static navigation icons |
-| State change icons (play → pause, like → liked) | Decorative icons |
-| Icons in contextual toolbars | Icons that are always visible |
-| Loading/success state indicators | Icon labels (text next to icon) |
-
-Use exactly these values for contextual icon animations. Do not deviate:
-- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
-- `opacity`: `0` → `1`
-- `filter`: `"blur(4px)"` → `"blur(0px)"`
-- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value
-

package/framework/skills/great-interface/references/icons.md

@@ -1,110 +0,0 @@
-# Icons
-
-Icon weight, states, sizing and direction, the details that make icons sit naturally in an interface.
-
-## Match icon stroke to text weight
-
-A hairline icon beside semibold text reads as broken; a heavy icon beside regular text shouts.
-
-| Adjacent text | Icon stroke width (24px grid) |
-| --- | --- |
-| Regular (400), 14–16px | `1.5px` |
-| Medium/Semibold (500–600) | `2px` |
-| Bold (700), or emphasized standalone | `2.5px` |
-
-```html
-<!-- Good: stroke tuned to the label weight -->
-<button class="flex items-center gap-2 font-semibold">
-  <PlusIcon stroke-width="2" class="size-4" />
-  New project
-</button>
-
-<!-- Bad: default 1.5px stroke against a bold label -->
-<button class="flex items-center gap-2 font-bold">
-  <PlusIcon stroke-width="1.5" class="size-4" />
-  New project
-</button>
-```
-
-Two related consistency rules:
-
-- **One optical strategy per surface.** Never mix icon libraries with incompatible stroke conventions on one toolbar. Where the library supports stroke variants, match them to adjacent text as above; otherwise keep the set's native stroke and use size or color for emphasis.
-- **Size icons relative to the text's cap height**, typically `1em`–`1.25em` when inline with text, so the pair scales together.
-
-## One SVG, recolored per state
-
-Never ship separate assets for default, hover, selected and disabled states. Use one SVG drawn with `currentColor` and let CSS state drive the color:
-
-```html
-<!-- Good: one asset, states are CSS -->
-<svg fill="none" stroke="currentColor" stroke-width="2">…</svg>
-```
-
-```css
-.icon-button { color: oklch(0.552 0.016 285.938); }
-.icon-button:hover { color: oklch(0.21 0.006 285.885); }
-.icon-button[aria-pressed="true"] { color: oklch(0.623 0.188 259.815); }
-.icon-button:disabled { opacity: 0.4; }
-```
-
-```html
-<!-- Tailwind -->
-<button class="text-zinc-500 hover:text-zinc-900 aria-pressed:text-blue-600 disabled:opacity-40">
-  <BookmarkIcon />
-</button>
-```
-
-Hardcoded fills inside the SVG, such as `fill="#666"`, break this. Strip them to `currentColor` when importing icons.
-
-## Outline default, fill active
-
-Where an icon set offers outline and filled variants, use them as a state pair, never interchangeably:
-
-| Variant | Use for |
-| --- | --- |
-| Outline | Default state: toolbars, list rows, inline with text |
-| Fill | Selected/active state: the active tab, a toggled bookmark, a liked heart |
-
-```tsx
-// Good: variant communicates state
-<TabIcon variant={isActive ? "solid" : "outline"} />
-
-// Bad: filled icons everywhere, so the active tab has no state signal
-<TabIcon variant="solid" />
-```
-
-The swap between variants is a contextual icon animation. Use the exact cross-fade values in [icon-transitions.md](icon-transitions.md).
-
-## Design at render size
-
-An icon that looks great at 48px collapses into mush at 16px. Thin interior lines, tight counters and fine texture all blur or alias when small.
-
-- Test every icon at the smallest size it will render, often `16px`. It must stay recognizable there.
-- Prefer simplified glyphs for small contexts over scaling down detailed artwork.
-- Keep icons on the pixel grid at their render size. A 16px icon drawn on a 24px grid with fractional scaling renders soft, so use the set's native grid sizes (`16`, `20`, `24`) rather than arbitrary scales.
-- Always SVG, never raster, so the same asset stays crisp at every density.
-
-## Icons in RTL
-
-Under `dir="rtl"`, flip icons whose meaning is tied to reading direction, and leave the rest alone:
-
-| Flip | Don't flip |
-| --- | --- |
-| Back/forward arrows, chevrons in navigation | Logos and brand marks |
-| Text-block glyphs (alignment, lists, indent) | Checkmarks |
-| Speaker/volume waves (emanate in reading direction) | Physical objects: clocks, cups, pencils |
-| "Send" style directional glyphs | Media playback (play/rewind refer to tape direction, convention keeps them LTR) |
-
-```css
-/* Good: mirror only direction-dependent icons */
-[dir="rtl"] .icon-directional {
-  scale: -1 1;
-}
-```
-
-```html
-<!-- Tailwind -->
-<ChevronRightIcon class="icon-directional rtl:-scale-x-100" />
-```
-
-Analyze composite icons part by part. A badge or slash overlay may keep its position even when the base glyph flips. Accessible names for icon-only buttons belong to `better-accessibility`.