---
name: scroll-hide-toolbar
description: Generate a standalone floating glass toolbar that contracts to a persistent circular profile control on downward scrolling and expands on upward scrolling. Use for mobile navigation prototypes and scroll-aware controls with configurable thresholds, colors, and light or dark themes.
---

# Scroll-aware floating toolbar

Generate a single offline HTML file with a scrollable two-column icon grid and a glass toolbar. The short glass capsule sits on the left and a separate circular plus button sits on the right. Downward scrolling contracts the capsule to a persistent profile control and hides the plus button; upward scrolling or returning near the top restores the expanded controls. View buttons demonstrate selection, and the plus button adds a sample icon. The sample grid does not launch apps or implement page routing.

## Generate

Requires Python 3.10+ and a modern browser. No third-party packages, build tools, remote fonts, or network requests are needed.

Run from this skill directory, or use the absolute path to the generator:

```bash
python3 scripts/generate.py -o out/index.html
python3 scripts/generate.py --title "My floating toolbar" --theme dark --accent "#ff5a36" --hideThreshold 12 -o out/custom.html
python3 scripts/generate.py --params params.json -o out/index.html
```

CLI flags override JSON values. Keep `scripts/` and `templates/` together. `preview.html` is a ready-to-open default output.

## Parameters

| Parameter | Default | Accepted values |
| --- | --- | --- |
| `title` | Scroll-aware toolbar | Non-empty plain text |
| `label` | Short scrolling description | Non-empty plain text |
| `theme` | `light` | `light` or `dark` |
| `accent` | `#2f7dff` | 3- or 6-digit hex color |
| `bg`, `stage`, `text`, `muted` | Theme-dependent | 3- or 6-digit hex colors; explicit overrides win |
| `hideThreshold` | `8` | Integer 1–100, accumulated pixels in one direction |
| `navHideMs` | `320` | Integer 0–2000, transition duration in milliseconds |
| `iconRadius` | `28%` | Integer percentage 0%–50% |
| `apps` (JSON only) | 12 sample items | 1–60 objects, each with `label` and `glyph` |

App labels must contain 1–100 characters. Available glyphs: `camera`, `maps`, `weather`, `share`, `translate`, `wallet`, `mail`, `passwords`, `music`, `settings`, `photos`, `notes`.

Example configuration:

```json
{
  "theme": "dark",
  "accent": "#ff5a36",
  "hideThreshold": 12,
  "apps": [
    {"label": "Library", "glyph": "photos"},
    {"label": "Inbox", "glyph": "mail"}
  ]
}
```

Use enough items to overflow the scroll region when testing hide/show behavior. Text and app labels remain literal, including HTML-like strings. Unknown parameters and invalid colors, ranges, themes, and glyphs are rejected.

## Integrate

Read [references/design.md](references/design.md) when adapting the layout or algorithm. The scroll listener is attached to `#scroller`, not the window. Bind it to the actual scrolling container in the target project; preserve the threshold reset on direction changes and the near-top reveal rule.

The profile control remains visible and keyboard accessible in the contracted state. Hidden controls become inert, so they cannot receive keyboard focus. The capsule stays expanded while a keyboard user focuses its other controls. Toolbar view buttons support Left/Right and Home/End; activating the persistent profile control expands the capsule. Reduced-motion settings remove transitions and make the sample addition scroll immediate.

## Verify

- Generate default and customized files and check the requested title, theme, accent, and thresholds.
- Inspect at 1440×900, 390×844, and 320px width. Scroll inside the icon grid, not the surrounding page.
- Scroll down beyond the threshold: only the profile circle remains. Reverse direction beyond the threshold: the short capsule and separate plus button return. Test repeated small deltas and direction reversals as well as large jumps.
- Select a view, use keyboard navigation, expand the contracted capsule from its profile control, and add a sample icon with the plus button. Check one selected view, visible focus, and no hidden tabbable controls.
- Check reduced motion, browser errors, and offline operation. Replace sample view actions with real navigation only when requested.