@fpkit/acss 6.2.0 → 6.4.0

package/src/components/buttons/button.scss

@@ -4,10 +4,14 @@ button {
   --btn-size-sm: 0.8125rem;
   --btn-size-md: 0.9375rem;
   --btn-size-lg: 1.125rem;
-  --btn-pill: 100rem;
+  --btn-size-xl: 1.375rem;
+  --btn-size-2xl: 1.75rem;
+  --btn-pill: 100vw;
   --btn-fs: var(--btn-size-md);
-  --btn-height: calc(var(--btn-fs) * 2.25);
-  --btn-bg: var(--color-neutral-300);
+
+  --btn-height: calc(var(--btn-fs) * 2.75);
+  --btn-bg: var(--color-primary);
+  --btn-color: var(--color-text-inverse);
   --btn-width: max-content;
 
   font-size: var(--btn-fs);
@@ -36,7 +40,7 @@ button {
   line-height: 0cap;
 
   &[type] {
-    background-color: var(--btn-bg, var(--color-neutral-300));
+    background-color: var(--btn-bg, var(--color-primary));
     --btn-border: solid var(--btn-sg);
   }
 
@@ -93,8 +97,77 @@ button {
 
   &[data-fp-btn~="pill"],
   &[data-btn~="pill"],
-  &[data-style~="pill"] {
-    border-radius: var(--btn-pill, 100rem);
+  &[data-style~="pill"],
+  &.btn-pill {
+    border-radius: var(--btn-pill, 100vw);
+  }
+
+  // Color variants — map to semantic tokens from index.css
+  &[data-color="primary"] {
+    --btn-bg: var(--color-primary);
+    --btn-color: var(--color-text-inverse);
+  }
+
+  &[data-color="secondary"] {
+    --btn-bg: var(--color-secondary);
+    --btn-color: var(--color-text-inverse);
+  }
+
+  &[data-color="danger"] {
+    --btn-bg: var(--color-error);
+    --btn-color: var(--color-text-inverse);
+  }
+
+  &[data-color="success"] {
+    --btn-bg: var(--color-success);
+    --btn-color: var(--color-text-inverse);
+  }
+
+  &[data-color="warning"] {
+    --btn-bg: var(--color-warning);
+    --btn-color: var(--color-text-inverse);
+  }
+
+  // Style variants via data-style (variant prop) — mirrors link button patterns
+  &[data-style~="outline"] {
+    --btn-bg: transparent;
+    --btn-color: currentColor;
+    --btn-border: 0.125rem solid currentColor;
+
+    &:is(:hover, :focus) {
+      background-color: color-mix(in srgb, currentColor 10%, transparent);
+      filter: none;
+      outline: 0.025rem solid currentColor;
+      outline-offset: 0;
+    }
+  }
+
+  &[data-style~="text"] {
+    --btn-bg: transparent;
+    --btn-color: currentColor;
+    --btn-border: none;
+    --btn-height: unset;
+    --btn-width: unset;
+    --btn-padding-block: 0.75rem;
+    --btn-padding-inline: 0.75rem;
+    &:is(:hover, :focus) {
+      background-color: color-mix(in srgb, var(--btn-color) 10%, transparent);
+      outline: 0.025rem solid var(--btn-color);
+      outline-offset: 0;
+      filter: none;
+    }
+  }
+
+  &[data-style~="icon"] {
+    padding: unset;
+    height: unset;
+    --btn-bg: transparent;
+    min-width: 1.5rem;
+    min-height: 1.5rem;
+    text-align: center;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
   }
 
   &[data-btn~="xs"],
@@ -118,16 +191,20 @@ button {
     --btn-fs: var(--btn-size-lg);
   }
 
-  &[data-btn~="icon"],
-  .btn-icon {
-    padding: unset;
-    height: unset;
-    --btn-bg: transparent;
-    min-width: 1.5rem;
-    min-height: 1.5rem;
-    text-align: center;
-    display: inline-flex;
-    align-items: center;
+  &[data-btn~="xl"],
+  .btn-xl {
+    --btn-fs: var(--btn-size-xl);
+  }
+
+  &[data-btn~="2xl"],
+  .btn-2xl {
+    --btn-fs: var(--btn-size-2xl);
+  }
+
+  &[data-btn~="block"],
+  .btn-block {
+    --btn-width: 100%;
+    display: flex;
     justify-content: center;
   }
 

package/src/components/buttons/button.stories.tsx

@@ -14,6 +14,27 @@ const meta = {
     children: "Click me",
     onClick: buttonClicked,
   },
+  argTypes: {
+    size: {
+      control: "select",
+      options: ["xs", "sm", "md", "lg", "xl", "2xl"],
+      description: "Size token — maps to data-btn attribute",
+    },
+    block: {
+      control: "boolean",
+      description: "Stretch button to 100% container width — composes with size and variant",
+    },
+    variant: {
+      control: "select",
+      options: ["text", "pill", "icon", "outline"],
+      description: "Style variant — maps to data-style attribute",
+    },
+    color: {
+      control: "select",
+      options: ["primary", "secondary", "danger", "success", "warning"],
+      description: "Color variant using semantic design tokens — maps to data-color attribute",
+    },
+  },
   parameters: {},
 } as Meta;
 
@@ -109,6 +130,132 @@ export const Large: Story = {
   },
 } as Story;
 
+// --- Size prop stories (typed API instead of raw data-btn) ---
+
+export const SizeXS: Story = {
+  args: { size: "xs", children: "Extra Small" },
+} as Story;
+
+export const SizeSM: Story = {
+  args: { size: "sm", children: "Small" },
+} as Story;
+
+export const SizeLG: Story = {
+  args: { size: "lg", children: "Large" },
+} as Story;
+
+export const SizeXL: Story = {
+  args: { size: "xl", children: "Extra Large" },
+} as Story;
+
+export const Size2XL: Story = {
+  args: { size: "2xl", children: "2X Large" },
+} as Story;
+
+// --- Block stories ---
+
+/**
+ * Block button — stretches to 100% container width at the default size.
+ */
+export const Block: Story = {
+  args: { block: true, children: "Block Button" },
+} as Story;
+
+/**
+ * Block button composed with size and color variants.
+ */
+export const BlockVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem", maxWidth: "32rem" }}>
+      <Button type="button" block size="sm">Block Small</Button>
+      <Button type="button" block>Block Default</Button>
+      <Button type="button" block size="lg">Block Large</Button>
+      <Button type="button" block size="xl" color="primary">Block XL Primary</Button>
+      <Button type="button" block color="danger" variant="outline">Block Danger Outline</Button>
+    </div>
+  ),
+} as Story;
+
+// --- Variant stories ---
+
+export const Outline: Story = {
+  args: { variant: "outline", children: "Outline" },
+} as Story;
+
+export const Pill: Story = {
+  args: { variant: "pill", children: "Pill" },
+} as Story;
+
+export const TextVariant: Story = {
+  args: { variant: "text", children: "Text Button" },
+} as Story;
+
+// --- Color stories ---
+
+export const Primary: Story = {
+  args: { color: "primary", children: "Primary" },
+} as Story;
+
+export const Secondary: Story = {
+  args: { color: "secondary", children: "Secondary" },
+} as Story;
+
+export const Danger: Story = {
+  args: { color: "danger", children: "Danger" },
+} as Story;
+
+export const Success: Story = {
+  args: { color: "success", children: "Success" },
+} as Story;
+
+export const Warning: Story = {
+  args: { color: "warning", children: "Warning" },
+} as Story;
+
+// --- Combination stories ---
+
+export const PrimaryOutline: Story = {
+  args: { color: "primary", variant: "outline", children: "Primary Outline" },
+} as Story;
+
+export const DangerPill: Story = {
+  args: { color: "danger", variant: "pill", children: "Danger Pill" },
+} as Story;
+
+export const SuccessOutline: Story = {
+  args: { color: "success", variant: "outline", children: "Success Outline" },
+} as Story;
+
+/**
+ * All color variants side by side.
+ */
+export const AllColors: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+      <Button type="button" color="primary">Primary</Button>
+      <Button type="button" color="secondary">Secondary</Button>
+      <Button type="button" color="danger">Danger</Button>
+      <Button type="button" color="success">Success</Button>
+      <Button type="button" color="warning">Warning</Button>
+    </div>
+  ),
+} as Story;
+
+/**
+ * All variant styles side by side.
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap", alignItems: "center" }}>
+      <Button type="button" variant="outline">Outline</Button>
+      <Button type="button" variant="pill">Pill</Button>
+      <Button type="button" variant="text">Text</Button>
+      <Button type="button" color="primary" variant="outline">Primary Outline</Button>
+      <Button type="button" color="danger" variant="pill">Danger Pill</Button>
+    </div>
+  ),
+} as Story;
+
 export const Custom: Story = {
   args: {
     styles: {
@@ -377,6 +524,8 @@ export const Customization: Story = {
 - \`--btn-size-sm\`: 0.8125rem (13px)
 - \`--btn-size-md\`: 0.9375rem (15px)
 - \`--btn-size-lg\`: 1.125rem (18px)
+- \`--btn-size-xl\`: 1.375rem (22px)
+- \`--btn-size-2xl\`: 1.75rem (28px)
 
 ### Base Properties
 - \`--btn-padding-inline\`: Horizontal padding (logical property)

package/src/components/buttons/button.test.tsx

@@ -79,6 +79,18 @@ describe("Button", () => {
     expect(handlePointerEvents).toHaveBeenCalledTimes(1);
   });
 
+  it("applies xl size via data-btn attribute", () => {
+    render(<Button type="button" size="xl">XL</Button>);
+    const button = screen.getByRole("button");
+    expect(button).toHaveAttribute("data-btn", "xl");
+  });
+
+  it("applies 2xl size via data-btn attribute", () => {
+    render(<Button type="button" size="2xl">2XL</Button>);
+    const button = screen.getByRole("button");
+    expect(button).toHaveAttribute("data-btn", "2xl");
+  });
+
   it("it is disabled when disabled is true", () => {
     const handleClick = jest.fn();
     render(

package/src/components/buttons/button.tsx

@@ -11,6 +11,39 @@ export type ButtonProps = Partial<React.ComponentProps<typeof UI>> &
      * Required - 'button' | 'submit' | 'reset'
      */
     type: "button" | "submit" | "reset";
+    /**
+     * Raw data-btn tokens. Merged with `size` and `block` — all three contribute
+     * whitespace-separated words to the final `data-btn` attribute value.
+     * @example <Button data-btn="pill">Pill button</Button>
+     */
+    "data-btn"?: string;
+    /**
+     * Size variant - maps to `data-btn` attribute, aligns with SCSS size tokens.
+     * Can coexist with a directly passed `data-btn` attribute (values are merged).
+     * @example <Button size="sm">Small</Button>
+     */
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+    /**
+     * Style variant - maps to `data-style` attribute.
+     * - `"outline"` — transparent bg with border (mirrors link button style)
+     * - `"pill"` — fully rounded corners
+     * - `"text"` — ghost text button with subtle hover
+     * - `"icon"` — square icon-only, no padding
+     * @example <Button variant="outline">Bordered</Button>
+     */
+    variant?: "text" | "pill" | "icon" | "outline";
+    /**
+     * Color variant - maps to `data-color` attribute using semantic color tokens.
+     * @example <Button color="danger">Delete</Button>
+     */
+    color?: "primary" | "secondary" | "danger" | "success" | "warning";
+    /**
+     * Block layout — stretches the button to 100% of its container width.
+     * Composes with `size` and other `data-btn` values.
+     * @example <Button block>Full Width</Button>
+     * @example <Button size="lg" block>Large Full Width</Button>
+     */
+    block?: boolean;
   };
 
 /**
@@ -73,6 +106,10 @@ export const Button = ({
   disabled,
   isDisabled,
   classes,
+  size,
+  variant,
+  color,
+  block,
   onPointerDown,
   onPointerOver,
   onPointerLeave,
@@ -96,30 +133,37 @@ export const Button = ({
       className: classes,
       // Note: onPointerOver and onPointerLeave are intentionally NOT wrapped
       // to allow hover effects on disabled buttons for visual feedback
-    }
+    },
   );
 
+  // Merge size, block, and any explicit data-btn passed by the consumer.
+  // SCSS uses [data-btn~="value"] (whitespace word match), so "lg block" targets both.
+  const { "data-btn": dataBtnProp, ...restProps } = props;
+  const dataBtnValue =
+    [size, block ? "block" : undefined, dataBtnProp]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
   /* Returning a button element with accessible disabled state */
   return (
     <UI
       as="button"
       type={type}
+      data-btn={dataBtnValue}
+      data-style={variant}
+      data-color={color}
       aria-disabled={disabledProps["aria-disabled"]}
       onPointerOver={onPointerOver}
       onPointerLeave={onPointerLeave}
       style={styles}
       className={disabledProps.className}
+      {...restProps}
       {...handlers}
-      {...props}
     >
       {children}
     </UI>
   );
 };
 
-export const IconButton = ({ icon, ...props }: ButtonProps) => {
-  return <Button {...props}>{icon}</Button>;
-};
-
 export default Button;
 Button.displayName = "Button";

package/src/components/buttons/icon-button.mdx

@@ -0,0 +1,204 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.React Components/Buttons/IconButton/Readme" />
+
+# IconButton
+
+## Summary
+
+`IconButton` is an accessible icon-button component that wraps the base `Button`
+with enforced accessible labelling and icon-specific defaults.
+
+It handles the two most common icon-button patterns:
+
+- **Icon-only** — a square tap target with a screen-reader label
+- **Icon + label** — icon with visible text that hides on narrow viewports
+
+`IconButton` extends all `Button` props (`size`, `variant`, `color`, `disabled`,
+etc.) and enforces one critical constraint at the TypeScript level: exactly one
+of `aria-label` or `aria-labelledby` must be present — passing both or neither
+is a compile-time error.
+
+---
+
+## Props
+
+| Prop              | Type                                                                 | Default    | Description                                                                                  |
+| ----------------- | -------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------- |
+| `icon`            | `React.ReactNode`                                                    | —          | **Required.** The icon element rendered inside the button.                                   |
+| `aria-label`      | `string`                                                             | —          | Accessible name for icon-only buttons. XOR with `aria-labelledby`.                          |
+| `aria-labelledby` | `string`                                                             | —          | References an external element's `id` as the accessible name. XOR with `aria-label`.        |
+| `label`           | `string`                                                             | —          | Optional label text alongside the icon. Hidden below `48rem` (768px); always in the accessibility tree.|
+| `type`            | `'button' \| 'submit' \| 'reset'`                                    | `'button'` | Button type attribute. Required.                                                             |
+| `variant`         | `'icon' \| 'outline' \| 'text' \| 'pill'`                           | `'icon'`   | Style variant. Default `'icon'` gives a transparent, square, no-padding button.             |
+| `size`            | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                    | —          | Size token. Scales font size and height via `--btn-fs`.                                      |
+| `color`           | `'primary' \| 'secondary' \| 'danger' \| 'success' \| 'warning'`   | —          | Semantic color token. Sets `--btn-bg` and `--btn-color` via `data-color`.                   |
+| `disabled`        | `boolean`                                                            | `false`    | Disables the button using WCAG-compliant `aria-disabled` (stays keyboard-focusable).        |
+| `onClick`         | `(e: React.MouseEvent<HTMLButtonElement>) => void`                   | —          | Click handler.                                                                               |
+| `styles`          | `React.CSSProperties`                                                | —          | Inline styles — use to override CSS custom properties e.g. `--btn-color: red`.             |
+| `classes`         | `string`                                                             | —          | Additional CSS classes appended to the button element.                                       |
+
+---
+
+## Sizing — 3rem Fixed Tap Target
+
+The default `variant="icon"` applies a fixed `width: 3rem; height: 3rem` to
+every `IconButton` instance:
+
+```css
+button[data-icon-btn] {
+  width: 3rem;   /* 48px at default font size */
+  height: 3rem;  /* 48px at default font size */
+}
+```
+
+`3rem` equals **48px** at the browser's default 16px root font size, meeting
+the WCAG 2.5.5 (AAA) minimum target size recommendation of 44×44 CSS pixels.
+The fixed size ensures a consistent, touchable target regardless of icon size
+or parent context.
+
+When a `label` is present (the `has-label` variant), width becomes `max-content`
+and padding is restored to `0.75rem` inline, but the `3rem` height is preserved
+for a consistent touch target.
+
+---
+
+## Label Visibility
+
+When `label` is provided, the text is rendered in a `<span data-icon-label>`.
+Visibility is controlled entirely by CSS — no prop required:
+
+- **Below `48rem` (768px):** the span is visually hidden via the visually-hidden
+  technique applied by the `[data-icon-label]` media query in `icon-button.scss`.
+  The span remains in the DOM and the accessibility tree — screen readers
+  announce the label at every viewport size.
+- **At `48rem` and above:** the label is fully visible alongside the icon.
+
+The breakpoint is a SCSS variable (not a CSS custom property) because media
+query conditions are evaluated at parse time and cannot reference runtime values:
+
+```scss
+$icon-label-bp: 48rem !default; // Override before import to customise
+```
+
+---
+
+## Usage Examples
+
+### Icon-only button
+
+Requires `aria-label`. The label is only announced by screen readers — not
+visible on screen.
+
+```tsx
+import { IconButton } from "@fpkit/acss";
+
+<IconButton
+  type="button"
+  aria-label="Close menu"
+  icon={<CloseIcon />}
+/>
+```
+
+### Icon + visible label
+
+Use `variant="outline"` (or any non-`icon` variant) to restore padding alongside
+the label. The default `variant="icon"` sets `padding: 0`, which collapses the
+layout around a label. The label hides automatically on mobile (< 48rem) via CSS.
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Settings"
+  icon={<SettingsIcon />}
+  label="Settings"
+  variant="outline"
+/>
+```
+
+### Labelled by external element
+
+Use `aria-labelledby` to reference an existing label element in the DOM. Useful
+when the button sits next to a heading or description that already names the action.
+
+```tsx
+<span id="delete-label">Delete item</span>
+<IconButton
+  type="button"
+  aria-labelledby="delete-label"
+  icon={<TrashIcon />}
+/>
+```
+
+### Semantic color variants
+
+Color tokens apply to the icon via `currentColor` — the icon's `stroke` or
+`fill` inherits the button's `--btn-color`.
+
+```tsx
+<IconButton type="button" aria-label="Delete" icon={<TrashIcon />} color="danger" />
+<IconButton type="button" aria-label="Confirm" icon={<CheckIcon />} color="success" />
+<IconButton type="button" aria-label="Settings" icon={<GearIcon />} color="primary" variant="outline" />
+```
+
+### Disabled state
+
+Uses the WCAG-compliant `aria-disabled` pattern — the button remains focusable
+and visible in the tab order so keyboard users can discover it and read any
+associated tooltip or help text.
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Upload (unavailable)"
+  icon={<UploadIcon />}
+  disabled
+/>
+```
+
+### Custom color via CSS custom property
+
+```tsx
+<IconButton
+  type="button"
+  aria-label="Star"
+  icon={<StarIcon />}
+  styles={{ "--btn-color": "#f59e0b" }}
+/>
+```
+
+---
+
+## Accessibility Notes
+
+- **`aria-label` is required** for icon-only buttons. An icon with no label
+  gives screen reader users no indication of the button's purpose.
+- **XOR enforcement** — the TypeScript type allows exactly one of `aria-label`
+  or `aria-labelledby`. Passing both or neither is a compile-time error.
+- **`label` does not replace `aria-label`** — even when a visible `label` is
+  provided, you must still pass `aria-label` (or `aria-labelledby`). The `label`
+  prop controls visual presentation only; `aria-label` provides the computed
+  accessible name.
+- **`disabled` keeps focus** — `IconButton` uses `aria-disabled="true"` instead
+  of the native `disabled` attribute. The button stays in the tab order and can
+  receive focus, satisfying WCAG 2.1.1 (Keyboard) and 4.1.2 (Name, Role, Value).
+- **Icon `aria-hidden`** — always render icons with `aria-hidden="true"` so
+  screen readers do not double-announce both the SVG content and the button label.
+
+```tsx
+// Correct — icon is decorative, label carries the meaning
+<IconButton
+  type="button"
+  aria-label="Close"
+  icon={<svg aria-hidden="true">...</svg>}
+/>
+```
+
+---
+
+## Related
+
+- [Button README](./README.mdx) — base `Button` props and variants
+- [Button Styles](./STYLES.mdx) — full CSS custom property reference
+- [WCAG 2.5.5 Target Size](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html)
+- [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks.html)