@felloinnovations/brand-kit 0.4.0 → 0.5.1

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import * as class_variance_authority_types from 'class-variance-authority/types'
 import { VariantProps } from 'class-variance-authority';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 import { ClassValue } from 'clsx';
+export { ContractToken, PaletteName, contract, palettes } from './palettes.js';
 
 /**
  * Figma `Marketing - Design System 3.0` page 🔘 Button (722:4), as resolved in
@@ -13,6 +14,15 @@ import { ClassValue } from 'clsx';
  * The Primary theme's 3px bottom border is not decoration. It is the lift, and
  * :active collapses it so the button physically presses. Drop it and the CTA
  * stops looking like Fello's.
+ *
+ * In step with `.ws-kit-button` (design-system/components/KitButton/style.css):
+ * the heights are floors, so a label too long for its column wraps to a second,
+ * balanced line instead of running out of the button; focus is the house ring
+ * (2px navy, 2px out); on touch, medium and small take a 44px hit area.
+ *
+ * Primary's words are white on the salmon gradient, as fello.ai draws them
+ * (Amit, 4 Nov 2026). That is 2.44 to 2.65:1, the kit's one logged exception
+ * to D2: the act is large, semibold and short. Literal in every theme.
  */
 declare const buttonVariants: (props?: ({
     variant?: "primary" | "secondary" | "navy" | "tertiary" | "clean" | null | undefined;
@@ -36,6 +46,11 @@ declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAtt
  * colours are fills: salmon on its own 12% tint is 2.39:1 and cannot carry
  * words. The *-strong tokens are those hues darkened until they clear 4.5:1,
  * which is why a salmon badge's label is not salmon.
+ *
+ * In step with `.ws-kit-badge` (design-system/components/Badge/style.css): the
+ * neutral ground is the track and navy words are the heading word, so both
+ * follow the theme. Its box is the CSS one too: 24px tall (`--space-lg`) with
+ * 16px lines, and the outline drawn inside, so every tone is the same size.
  */
 declare const badgeVariants: (props?: ({
     tone?: "navy" | "neutral" | "brand" | "success" | "error" | "outline" | null | undefined;
@@ -56,11 +71,19 @@ declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttri
  * and the hairline border already does the separating work. `surface="tinted"`
  * is there for the cases that genuinely need to recede.
  *
- * No shadow by default. Elevation is a signal, and a page where every card is
- * raised has no signal left. `interactive` adds the lift on hover for cards
- * that are actually clickable.
+ * No shadow, at rest or on hover. Elevation is a signal, and a page where every
+ * card is raised has no signal left. `interactive` tints the card on hover (the
+ * nav's hover wash over its own surface), a colour change rather than a lift
+ * (D7), which also shows on the dark ground where a shadow barely did.
  *
  * Parts mirror shadcn's Card, so a call site migrates by changing the import.
+ *
+ * In step with `.ws-kit-card` (design-system/components/KitCard/style.css):
+ * the surface follows the theme (`--color-surface`), tinted is the sunk step,
+ * and a long title breaks rather than running out of the card. An interactive
+ * card is the link itself, so it takes focus and reads as one target:
+ * `<a href="/x" className={cardVariants({ interactive: true })}>`. A `<Card
+ * interactive>` div with an onClick is not reachable by keyboard.
  */
 declare const cardVariants: (props?: ({
     surface?: "white" | "tinted" | "transparent" | null | undefined;
@@ -85,7 +108,15 @@ declare const CardFooter: react.ForwardRefExoticComponent<react.HTMLAttributes<H
  * which keeps the markup readable and needs no JavaScript.
  *
  * The label is part of the control, so the tap target is the row rather than
- * an 18px square. That matters on phones, which is most of this audience.
+ * an 18px square. That matters on phones, which is most of this audience: on
+ * a coarse pointer the label's hit area covers the row, box included, 44px
+ * tall (the public floor), like Button's medium and small.
+ *
+ * In step with `.ws-check` (design-system/components/Checkbox/style.css),
+ * Seth's action box: 18px, 4px corners, a 1.5px navy edge on the page cream at
+ * rest (12:1, so the box passes the 3:1 a control asks), a navy wash under a
+ * pointer, navy when chosen with a 12px tick in the act's word. An invalid,
+ * empty box takes the needs-you edge. Focus is the house ring, 2px navy, 2px out.
  */
 interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
     label?: React.ReactNode;
@@ -96,8 +127,14 @@ declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.Re
 
 /**
  * Form Input, per docs-cache/design-system/cards-and-components.md §3:
- * 40px tall, 6px radius, 1px Gray Stroke, 9/12 padding, 14px Gray 8 text,
- * Gray 5 placeholder, salmon border + 3px salmon ring on focus.
+ * 40px tall, 6px radius, 1px Gray Stroke, 12px sides, 14px words,
+ * the placeholder word, a salmon border on error.
+ *
+ * In step with `.ws-kit-input` (design-system/components/KitInput/style.css):
+ * the field ground and words follow the theme (`--ws-field`, `--ws-field-ink`);
+ * focus is the house ring (2px navy, 2px out), not the salmon halo that made a
+ * field being typed in look refused; on touch the field is 44px with 16px words,
+ * so a phone does not zoom the page when it takes focus.
  *
  * `error` is a string, not a boolean, because an error state with no message
  * is not an accessible error state. Passing one wires aria-describedby and
@@ -140,6 +177,16 @@ declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & reac
  *
  * Two looks. `underline` is the marketing-page default. `pill` is for dense
  * internal tools, where a segmented control reads better than a rule.
+ *
+ * In step with `.ws-tabs` (design-system/components/Tabs/style.css): the
+ * current tab is navy words on a 2px navy rule (the old salmon rule was a
+ * 2.6:1 state mark), the others the body word. A row wider than its column
+ * (underline) scrolls sideways instead of pushing the page past a phone's
+ * edge, so the focus ring is drawn inside the tab (D8, a clipped container),
+ * and a tab never shrinks. `pill` does not scroll; keep a pill set to what
+ * fits. Its chosen tab is the navy thumb, as `Segmented` draws it, so it shows
+ * in dark as well, and its focus ring stands 2px off the thumb. On touch a tab is 44px tall, the public page's floor, like
+ * Button and Input. `pill` hugs its tabs rather than spanning the column.
  */
 type Variant = 'underline' | 'pill';
 interface TabsProps extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root> {
@@ -150,12 +197,17 @@ declare const TabsList: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsL
 declare const TabsTrigger: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
 declare const TabsContent: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
-/** 12px / 500 / Gray 7, per the Figma input annotation block. */
+/** 12px / 500, per the Figma input annotation block, in the body word (Gray 7 in light; it follows the theme). */
 declare const Label: react.ForwardRefExoticComponent<react.LabelHTMLAttributes<HTMLLabelElement> & react.RefAttributes<HTMLLabelElement>>;
 
 /**
- * Loading placeholder. Gray 2 so it reads as absent rather than as content.
- * Respects prefers-reduced-motion by dropping the pulse, not the block.
+ * Loading placeholder: a ghost the shape of what is coming, under North's
+ * shimmer in one quiet grey (0.5.1), never a spinner. The ghost is the
+ * `--ws-shimmer` gradient, so it reads as absent rather than as content in
+ * either theme. The sweep runs where fello.css is on the page (`ws-shimmer`,
+ * the house class) and stops under prefers-reduced-motion; with tokens.css
+ * alone it is the still ghost. 4px corners, as `.ws-skeleton`
+ * (design-system/components/Skeleton/style.css).
  */
 declare function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): react.JSX.Element;
 
@@ -171,6 +223,13 @@ declare function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivE
  *
  * A zero is a claim about the business that may be false; an X reads as
  * "this broke"; a dash reads as "nothing here yet", which is the only true one.
+ *
+ * In step with `.ws-stat` (design-system/components/Stat/style.css): the figure
+ * is the kit's 28/32 row step, the label 12px (the public web's smallest label),
+ * `brand` takes salmon's word step (salmon itself is 2.7:1, under the 3:1 a
+ * 28px figure needs), and pending is the shimmer ghost at the figure's height,
+ * so nothing shifts when the number lands. The sweep runs where fello.css is on
+ * the page (`ws-shimmer`); with tokens.css alone it is the still ghost.
  */
 interface StatProps {
     label: string;
@@ -186,4 +245,44 @@ declare function Stat({ label, value, note, tone, pending, className }: StatProp
 /** Merge class names, last Tailwind utility wins. */
 declare const cn: (...inputs: ClassValue[]) => string;
 
-export { Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, Checkbox, type CheckboxProps, Input, type InputProps, Label, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Skeleton, Stat, type StatProps, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, badgeVariants, buttonVariants, cardVariants, cn };
+/**
+ * Seth's motion where CSS cannot start it alone (D7, design-system/components/Morph and Composer). No framework, no
+ * per-frame script: each helper hands the move to the browser and the kit's CSS.
+ */
+/** Which of Seth's moves a morph is (Morph/README.md): `full` a card to full screen and back (.45 s, the morph curve),
+ *  `grow` a card growing open (.55 s, grow), `shrink` it closing back into place (.4 s, grow), `shift` the chat moving
+ *  between its modes (.55 s, shift). */
+type MorphKind = 'full' | 'grow' | 'shrink' | 'shift';
+interface MorphOptions {
+    /** The move, by Seth's name for it. Default `full`. */
+    as?: MorphKind;
+    /** The element that changes place or size, still in the page after the update (the same node). morph() names it
+     *  `ws-morph` for the move and copies its ground and corners to the frame. Leave it out when the page names its own
+     *  element (`view-transition-name: ws-morph`). For `full` it is required: it is the element lifted to the top layer. */
+    el?: HTMLElement | null;
+    /** `full` only: the update that brings the element back, which Escape runs (as a morph). Leave it out when `update`
+     *  is a toggle (it flips the full state both ways): Escape then runs `update` again. */
+    close?: () => void | Promise<void>;
+}
+/**
+ * Runs `update` (the change of class, mode or place) as a same-document view transition, so the element goes to its new
+ * place as itself on Seth's curve for `as`. Without view transitions, or under reduced motion, it runs `update` at once.
+ * Resolves when the move has finished. In React, flush the state inside it: `morph(() => flushSync(() => setFull(true)), { el })`.
+ *
+ * `full` also lifts `el` into the top layer while its update leaves it `position: fixed`, and brings it back down when
+ * an update leaves it unfixed (see place()): the full screen covers the window whatever the element sits inside. That
+ * happens with or without motion. Escape runs `close` (or `update` again, for a toggle); give the full state a Back
+ * button that calls morph() the same way.
+ */
+declare function morph(update: () => void | Promise<void>, { as, el, close }?: MorphOptions): Promise<void>;
+/**
+ * North's placeholder roll ("Placeholder roll": every 3.4 s the next question rolls up out of a blur on the roll spring).
+ * Moves `data-on` to the next line of a `ws-composer__roll` every `every` ms; the CSS does the motion. Returns a stop
+ * (a React effect's cleanup: `useEffect(() => rollPlaceholder(ref.current!), [])`). Under reduced motion it holds the
+ * first line.
+ */
+declare function rollPlaceholder(roll: Element, every?: number): () => void;
+
+declare function reorder(update: () => unknown, within?: ParentNode, rows?: string): Promise<void>;
+
+export { Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, Checkbox, type CheckboxProps, Input, type InputProps, Label, type MorphKind, type MorphOptions, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Skeleton, Stat, type StatProps, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, badgeVariants, buttonVariants, cardVariants, cn, morph, reorder, rollPlaceholder };