@mohammadhprp/system-prompt 0.12.2 → 0.12.3

package/framework/skills/great-interface/references/spacing-and-adaptivity.md

@@ -1,159 +0,0 @@
-# Spacing and adaptivity
-
-Space between controls, margins against the viewport, hints at off-screen content and layouts that survive resizing and translation.
-
-## Breathing room between targets
-
-Controls placed too close get mis-tapped and read as one unit. Where the project has no density scale, start here:
-
-| Between | Starting point |
-| --- | --- |
-| Adjacent bordered/filled controls (buttons, inputs) | `12px` |
-| Around borderless controls (text buttons, icon buttons) | `24px` |
-| Unrelated control groups | `24px`+ (2× the intra-group gap) |
-
-Borderless controls need more clearance, because nothing marks where one target ends and the next begins. The space is the boundary. Compact professional tools may use less where hit areas stay distinct and never overlap. Preserve an established, usable density rather than expanding controls to match these values.
-
-```html
-<!-- Good: bordered buttons at 12px, icon buttons given room -->
-<div class="flex gap-3">
-  <button class="rounded-lg border px-4 py-2">Cancel</button>
-  <button class="rounded-lg bg-blue-600 px-4 py-2 text-white">Save</button>
-</div>
-
-<!-- Bad: three borderless icon buttons packed at 4px -->
-<div class="flex gap-1">
-  <button><TrashIcon /></button>
-  <button><ArchiveIcon /></button>
-  <button><ShareIcon /></button>
-</div>
-```
-
-WCAG target-size requirements, larger usability targets and pseudo-element expansion belong to `better-accessibility`; these clearances are in addition, so expanded hit areas never overlap.
-
-## Inset buttons from the edges
-
-In content layouts, buttons pressed against the viewport look like system chrome and clip against curved corners or gesture zones. Keep them inside the layout margins. Edge-to-edge actions stay valid where they are deliberately platform chrome and account for safe areas:
-
-```css
-/* Good: inset action bar */
-.action-bar {
-  padding-inline: 16px;
-  padding-bottom: calc(16px + env(safe-area-inset-bottom));
-}
-.action-bar button { width: 100%; border-radius: 12px; }
-
-/* Bad: button glued to all three edges */
-.action-bar button {
-  width: 100vw;
-  border-radius: 0;
-  position: fixed;
-  bottom: 0;
-}
-```
-
-Start near `16px` inline margin on mobile where the project has no layout token. The button can still span the full content width inside them.
-
-## Progressive disclosure needs an affordance
-
-Hiding complexity is good; hiding it without a cue is a trap. Every piece of off-screen or collapsed content needs a visible hint that it exists. Keep the product's established scroll indicator or disclosure pattern, and use the recipes below only where no cue exists:
-
-- **Peeking items.** In a horizontal scroller or carousel, size items so the next one peeks `16–32px` past the container edge. A row of cards that ends exactly at the edge looks complete, and nobody scrolls it.
-- **Disclosure controls.** Collapsed sections get a chevron or "Show more", labelled with what is hidden: "Show 12 more results", not "More".
-- **Truncation cues.** Clamped text shows an ellipsis and a way to expand. Truncation mechanics are `better-typography`'s.
-
-In the peeking-scroller recipe, the container's padding creates the peek and snap points stay on the content edge.
-
-```css
-.scroller {
-  display: flex;
-  gap: 12px;
-  overflow-x: auto;
-  padding-inline: 24px;
-  scroll-padding-inline: 24px;
-  scroll-snap-type: x mandatory;
-}
-.scroller > * {
-  flex: 0 0 calc(100% - 48px - 24px); /* container minus margins minus peek */
-  scroll-snap-align: start;
-}
-```
-
-```html
-<!-- Tailwind: the 80% width keeps the next card's leading 16-32px visible -->
-<div class="flex gap-3 overflow-x-auto px-6 [scroll-padding-inline:1.5rem] snap-x snap-mandatory">
-  <div class="w-[80%] shrink-0 snap-start">…</div>
-  <div class="w-[80%] shrink-0 snap-start">…</div>
-</div>
-```
-
-## Content bleeds, controls float
-
-The two layers behave differently at the edges:
-
-- **Content layer**: backgrounds, hero media and scrollable lists extend to the viewport edges.
-- **Control layer**: text and controls stay inside the layout margins and safe areas, floating above the content.
-
-```css
-/* Good: full-bleed media inside a constrained article */
-.article {
-  display: grid;
-  grid-template-columns: 1fr min(65ch, calc(100% - 48px)) 1fr;
-}
-.article > * { grid-column: 2; }
-.article > .full-bleed { grid-column: 1 / -1; }
-```
-
-Sticky headers and floating action buttons account for safe areas:
-
-```css
-.fab {
-  position: fixed;
-  inset-inline-end: calc(16px + env(safe-area-inset-right));
-  bottom: calc(16px + env(safe-area-inset-bottom));
-}
-```
-
-## Hold structure until it breaks
-
-Breakpoints belong to the content, not the device catalog:
-
-- Break where the layout actually stops fitting, not at `768px` because a preset says so. That is where the sidebar squeezes content below its minimum measure, or the card grid drops below a usable column width.
-- Collapse late. A layout keeping its expanded structure as long as it genuinely fits stays stable and familiar. Premature collapsing throws away space users paid for.
-- Prefer **container queries** for components. A card adapts to the column it is in, not to the viewport.
-
-```css
-/* Good: component adapts to its container */
-.card-list { container-type: inline-size; }
-@container (max-width: 400px) {
-  .card { grid-template-columns: 1fr; }
-}
-
-/* Bad: viewport media query breaks the card inside a narrow sidebar */
-@media (max-width: 768px) {
-  .card { grid-template-columns: 1fr; }
-}
-```
-
-Test the smallest and largest supported sizes first, since those break first, then the sizes between.
-
-## Plan for growth and clipping
-
-Layouts fail in two directions. Content grows, and viewports shrink.
-
-**String expansion varies by language and by source-string length.** Never rely on one universal percentage.
-
-- No fixed widths sized to English labels. Use `max-width` plus wrapping.
-- No fixed heights on text containers. Use `min-height` where a floor is needed.
-- Buttons size themselves from their label (`padding-inline`), never a hardcoded width.
-- Test with pseudo-localization or a long-string locale before shipping.
-
-```css
-/* Good: label defines the size */
-.button { padding-inline: 16px; white-space: nowrap; }
-
-/* Bad: German will overflow or truncate */
-.button { width: 96px; overflow: hidden; }
-```
-
-**Clipping.** Never park a critical action where it can be cut off: the bottom edge of a resizable pane, below the fold of a fixed-height modal, behind an expanding keyboard. Keep primary actions in stable chrome, a sticky footer with safe-area padding or the top of the view. Where a modal's content scrolls, its action row does not.

package/framework/skills/great-interface/references/spacing-and-sizing.md

@@ -1,121 +0,0 @@
-# Spacing and sizing
-
-A sensible scale and comfortable spacing do more for typography than any effect.
-
-## Units
-
-| Unit | Behavior |
-| --- | --- |
-| `px` | Fixed |
-| `em` | Scales with the current font size |
-| `rem` | Scales with the root font size |
-| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
-
-## Type scale
-
-A small set of sizes used across a product, deviated from as little as possible. Hard-coding sizes with no system behind them breaks down at scale.
-
-```css
-:root {
-  --text-sm: 0.875rem;
-  --text-base: 1rem;
-  --text-lg: 1.125rem;
-  --text-xl: 1.5rem;
-  --text-2xl: 2rem;
-}
-```
-
-Pick an existing scale or define one. Tailwind's (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
-
-Solo, the default names work fine given clear rules for where each size is used. On a team, name sizes semantically. `text-sm` tells you the size but not the use, where `text-body-sm` carries both.
-
-A role-based scale pairs each size with its line-height and weight, making a role one decision instead of three. A starting point for a product interface:
-
-| Role | Size | Line-height | Weight |
-| --- | --- | --- | --- |
-| Display | `2.25rem` (36px) | `1.1` | `600` |
-| Title | `1.5rem` (24px) | `1.2` | `600` |
-| Heading | `1.125rem` (18px) | `1.3` | `600` |
-| Body | `1rem` (16px) | `1.5` | `400` |
-| Caption | `0.8125rem` (13px) | `1.4` | `400` |
-
-Emphasis within a role is one weight step up (`400` → `500`), not a size change.
-
-## Heading hierarchy
-
-Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
-
-```css
-h1 { font-size: var(--text-2xl); }
-h2 { font-size: var(--text-xl); }
-h3 { font-size: var(--text-lg); }
-```
-
-In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), centralized in a component or `@layer base` rather than repeated inline.
-
-When reviewing, compare the computed size of headings within each semantic section. A child rendering more prominently than its parent breaks the hierarchy. Deep levels may share a size where the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading is never smaller than body text unless it is deliberately a label-style overline.
-
-Heading semantics and outline quality belong to `better-accessibility`. Pick the element from the document structure, then use this skill to make that structure visually legible. Never pick a heading element for its browser-default size.
-
-## Kerning and letter-spacing
-
-- **Kerning** adjusts specific pairs such as `AV` or `Ye`. It is built into the font and applied automatically. Switch it off only deliberately, with `font-kerning: none`.
-- **`letter-spacing`** adds the same space between every character.
-
-```css
-/* Good */
-.display-heading {
-  letter-spacing: -0.02em;
-}
-
-.uppercase-label {
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-}
-```
-
-## Line-height
-
-| Text | Value |
-| --- | --- |
-| Headings | ~`1.1` |
-| Body copy | `1.5`–`1.6` |
-
-Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding. A tightly-leaded paragraph is harder to read than a taller row is to fit.
-
-```css
-/* Bad: card description at heading leading */
-.card-description { line-height: 1.1; }
-
-/* Good: it wraps to 3 lines, so it reads as body text */
-.card-description { line-height: 1.4; }
-```
-
-## Text trimming with text-box
-
-Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
-
-| Keyword | Trims at |
-| --- | --- |
-| `cap` | The cap height (top) |
-| `alphabetic` | The baseline (bottom) |
-| `text` | The font's own text edge, keeping room for descenders |
-
-```css
-/* trim top and bottom */
-.badge {
-  text-box: trim-both cap alphabetic;
-}
-
-/* trim only the top */
-.heading {
-  text-box: trim-start cap;
-}
-
-/* trim only the bottom */
-.label {
-  text-box: trim-end alphabetic;
-}
-```
-
-Supported in Chromium (133+) and Safari (18.2+), not yet Firefox. Treat it as progressive enhancement, where unsupported browsers keep the default leading.

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

@@ -1,219 +0,0 @@
-# Surfaces
-
-Border radius, optical alignment, shadows and image outlines.
-
-## Concentric border radius
-
-When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
-
-```
-outerRadius = innerRadius + padding
-```
-
-The rule matters most when nested surfaces sit close together. Past `24px` of padding, treat the layers as separate surfaces and choose each radius independently rather than forcing concentric math.
-
-### Example
-
-```css
-/* Good: concentric radii */
-.card {
-  border-radius: 20px; /* 12 + 8 */
-  padding: 8px;
-}
-.card-inner {
-  border-radius: 12px;
-}
-
-/* Bad: same radius on both */
-.card {
-  border-radius: 12px;
-  padding: 8px;
-}
-.card-inner {
-  border-radius: 12px;
-}
-```
-
-### Tailwind example
-
-```tsx
-// Good: outer radius accounts for padding
-<div className="rounded-2xl p-2">       {/* 16px radius, 8px padding */}
-  <div className="rounded-lg">          {/* 8px radius = 16 - 8 ✓ */}
-    ...
-  </div>
-</div>
-
-// Bad: same radius on both
-<div className="rounded-xl p-2">
-  <div className="rounded-xl">          {/* same radius, looks off */}
-    ...
-  </div>
-</div>
-```
-
-Mismatched radii on closely nested surfaces are a common source of visual tension. Calculate concentrically where the layers share a visible, even inset. Keep an established component token where they are independent or the padding is deliberately asymmetric.
-
-## Optical alignment
-
-When geometric centering looks off, align optically instead.
-
-### Buttons with text + icon
-
-Where an icon makes symmetric padding look unbalanced, use slightly less on the icon side. A starting point:
-`icon-side padding = text-side padding - 2px`.
-
-```css
-/* Good: less padding on icon side */
-.button-with-icon {
-  padding-inline-start: 16px;
-  padding-inline-end: 14px; /* trailing icon side = text side - 2px */
-}
-
-/* Bad: equal padding looks like icon is pushed too far right */
-.button-with-icon {
-  padding-inline: 16px;
-}
-```
-
-```tsx
-// Tailwind
-<button className="ps-4 pe-3.5 flex items-center gap-2">
-  <span>Continue</span>
-  <ArrowRightIcon />
-</button>
-```
-
-### Play button triangles
-
-Play icons are triangular and their geometric center is not their visual center. Shift slightly right:
-
-```css
-/* Good: optically centered */
-.play-button svg {
-  transform: translateX(2px); /* physical correction to the glyph itself */
-}
-
-/* Bad: geometrically centered but looks off */
-.play-button svg {
-  /* no adjustment */
-}
-```
-
-### Asymmetric icons (stars, arrows, carets)
-
-Some icons carry uneven visual weight. The best fix is adjusting the SVG directly, so the component needs no extra margin or padding.
-
-```tsx
-// Best: fix in the SVG itself
-// Adjust the viewBox or path to visually center the icon
-
-// Fallback: adjust with margin
-<span className="translate-x-px">
-  <StarIcon />
-</span>
-```
-
-## Shadows instead of borders
-
-Where **buttons, cards and containers** use a border for depth or elevation, replace it with a subtle `box-shadow`. Shadows use transparency, so they adapt to any background where solid borders do not. That matters most over images or multiple background colors, which a fixed border color was never designed for.
-
-**Never apply this to dividers**, meaning `border-b`, `border-t` and side borders, or any border whose purpose is layout separation rather than depth. Those stay borders.
-
-### Shadow as border (light mode)
-
-Three layers. The first acts as a 1px border ring, the second adds subtle lift, the third ambient depth:
-
-```css
-:root {
-  --shadow-border:
-    0px 0px 0px 1px oklch(0 0 0 / 0.06),
-    0px 1px 2px -1px oklch(0 0 0 / 0.06),
-    0px 2px 4px 0px oklch(0 0 0 / 0.04);
-  --shadow-border-hover:
-    0px 0px 0px 1px oklch(0 0 0 / 0.08),
-    0px 1px 2px -1px oklch(0 0 0 / 0.08),
-    0px 2px 4px 0px oklch(0 0 0 / 0.06);
-}
-```
-
-### Shadow as border (dark mode)
-
-In dark mode, simplify to one white ring, since layered depth shadows are invisible on dark backgrounds:
-
-```css
-/* Dark mode: adapt to whatever setup the project uses
-   (prefers-color-scheme, class, data attribute, etc.) */
---shadow-border: 0 0 0 1px oklch(1 0 0 / 0.08);
---shadow-border-hover: 0 0 0 1px oklch(1 0 0 / 0.13);
-```
-
-### Usage with hover transition
-
-Apply the variable and add `transition-[box-shadow]` for a smooth hover:
-
-```css
-.card {
-  box-shadow: var(--shadow-border);
-  transition-property: box-shadow;
-  transition-duration: 150ms;
-  transition-timing-function: ease-out;
-}
-
-.card:hover {
-  box-shadow: var(--shadow-border-hover);
-}
-```
-
-### When to use shadows vs. borders
-
-| Use shadows | Use borders |
-| --- | --- |
-| Cards, containers with depth | Dividers between list items |
-| Buttons with bordered styles | Table cell boundaries |
-| Elevated elements (dropdowns, modals) | Form input outlines (for accessibility) |
-| Elements on varied backgrounds | Hairline separators in dense UI |
-| Hover/focus states for lift effect | |
-
-## Image outlines
-
-Add a `1px` outline at low opacity to images for consistent depth, especially where other elements use borders or shadows.
-
-### Color rules (non-negotiable)
-
-- **Light mode**: pure black, `oklch(0 0 0 / 0.1)`.
-- **Dark mode**: pure white, `oklch(1 0 0 / 0.1)`.
-- Never a near-black or near-white from the project palette, such as slate-900, zinc-900, `#0a0a0a`, `#111827`, or `#f5f5f7`. Tinted outlines pick up the surrounding surface color and read as dirt on the image edge.
-- Never match the outline to the project's accent or ink color. The outline is a neutral separator, not a themed element.
-
-### Light mode
-
-```css
-img {
-  outline: 1px solid oklch(0 0 0 / 0.1);
-  outline-offset: -1px; /* draw the ring just inside the image edge */
-}
-```
-
-### Dark mode
-
-```css
-img {
-  outline: 1px solid oklch(1 0 0 / 0.1);
-  outline-offset: -1px;
-}
-```
-
-### Tailwind with dark mode
-
-```tsx
-<img
-  className="outline outline-1 -outline-offset-1 outline-black/10 dark:outline-white/10"
-  src={src}
-  alt={alt}
-/>
-```
-
-Use `outline-black/10` and `outline-white/10` specifically, not `outline-slate-*`, `outline-zinc-*`, `outline-neutral-*`, or any tinted scale.
-
-**Why outline instead of border?** `outline` never affects layout, adding no width or height at any offset, and `outline-offset: -1px` draws the ring just inside the image edge so it hugs the corner radius.

package/framework/skills/great-interface/references/token-naming.md

@@ -1,97 +0,0 @@
-# Token naming
-
-Naming is what makes a palette usable by anyone who did not build it. For which ramps exist and what each step does, see [palette-structure.md](palette-structure.md).
-
-## Two tiers
-
-**Primitives** name a value. They are the ramp, named by hue and step: `--blue-500`, `--neutral-200`. A primitive describes what the color *is*, so it never changes meaning between themes and is never applied directly in a component.
-
-**Semantics** name a job. They point at a primitive and take the name of the role they fill: `--color-text-secondary`, `--color-border-subtle`. Components only ever reference this tier.
-
-```css
-:root {
-  /* Tier 1: primitives, named by appearance. Never used directly. */
-  --blue-500: #3b82f6;
-  --neutral-200: #e5e7eb;
-  --neutral-700: #374151;
-
-  /* Tier 2: semantics, named by role. This is what components use. */
-  --color-accent-solid: var(--blue-500);
-  --color-border: var(--neutral-200);
-  --color-text-secondary: var(--neutral-700);
-}
-```
-
-The tiering is what makes theming possible. Dark mode, a white-label theme and an increased-contrast variant all repoint the semantic tier, leaving the primitives and every component untouched. A codebase applying `--blue-500` directly in components has no theming seam. Adding one later means auditing every usage to work out which meant "the accent" and which just wanted blue.
-
-Add a third, component-level tier (`--color-button-danger-bg`) only where a component genuinely and intentionally diverges from the system. One component token is a documented exception; twenty mean the semantic tier is missing roles.
-
-## The role inventory
-
-A system is complete when every role below has a token. Build against this list rather than adding tokens as components demand them, or the palette ends up shaped like whichever screen came first.
-
-| Group | Roles |
-| --- | --- |
-| Surfaces | page background, surface, raised (menus, popovers), sunken (inputs, wells), overlay scrim |
-| Text | primary, secondary, disabled, inverse, on-accent |
-| Borders | subtle, default, strong, focus ring, separator |
-| Accent | subtle background, border, solid, solid hover, text |
-| Status | per status shipped: subtle background, border, solid, text |
-
-Separator and border are separate roles even when they share a value today. A separator divides content; a border encloses a control. They diverge the first time someone restyles inputs, and a system that conflated them gets untangled at that moment.
-
-## Naming grammar
-
-Use one shape and never deviate: `--color-{role}-{variant}-{state}`.
-
-```css
---color-bg-surface
---color-text-secondary
---color-border-strong
---color-accent-solid-hover
-```
-
-Pick one word per concept and use only that word. Consistency matters more than the vocabulary. A reader who has seen `--color-text-primary` must be able to guess `--color-text-disabled` without looking:
-
-| Concept | Pick one | Never mix in |
-| --- | --- | --- |
-| Foreground | `text` | `fg`, `foreground`, `content`, `ink` |
-| Background | `bg` | `background`, `surface` as a synonym, `fill` |
-| Edge | `border` | `stroke`, `outline`, `line` |
-| Brand color | `accent` | `primary`, `brand`, `theme` used interchangeably |
-
-Reserve `primary` for exactly one meaning. `--color-text-primary` for body text beside `--color-primary` for the brand is the most common naming collision there is, and it makes every `primary` token ambiguous until you open its definition. Use `accent` for the brand and let `primary` mean "the most prominent of its group".
-
-## Anti-patterns
-
-| Name | Problem | Instead |
-| --- | --- | --- |
-| `--color-blue-button` | Appearance at the semantic tier; lies the moment the brand changes | `--color-accent-solid` |
-| `--color-sidebar-gray` | Named for where it was used first; the second usage makes it nonsense | `--color-bg-surface` |
-| `--color-light-gray` | Lies in dark mode, where it is the dark one | `--neutral-200` as a primitive |
-| `--color-text-2` | Numbered semantics carry no meaning; nobody can guess what `3` would be | `--color-text-secondary` |
-| `--color-gray-hover` | Mixes a hue with a state and belongs to no tier | `--color-bg-surface-hover` |
-| `--blue-500` used in a component | Skips the semantic tier and removes the theming seam | Point a semantic token at it |
-
-Every one of them is a case of **Use a token only in its role**. See [color-usage.md](color-usage.md).
-
-## In Tailwind projects
-
-Tailwind v4 generates utilities from `@theme`, so names declared there become the API. Declare primitives and semantics in the same block; the `--color-*` namespace is what produces `bg-*`, `text-*` and `border-*`:
-
-```css
-@theme {
-  /* Primitives */
-  --color-brand-50: #eff6ff;
-  --color-brand-500: #3b82f6;
-  --color-brand-900: #1e3a8a;
-
-  /* Semantics: what templates should use */
-  --color-accent-solid: var(--color-brand-500);
-  --color-text-secondary: var(--color-neutral-700);
-}
-```
-
-That yields `bg-accent-solid` and `text-secondary` alongside `bg-brand-500`. Both are reachable, so the discipline is a convention rather than a constraint. Templates use the semantic utilities, and a raw `bg-brand-500` in a component is the thing to flag.
-
-Opacity modifiers work on either tier, as in `bg-accent-solid/50`. But a color carrying alpha cannot be contrast-checked against a static background, because what it renders depends on what sits behind it. Use solid tokens for anything with text on it.