FE-1708: Add Petricon to Petrinaut

[kube]

Important

Experimental
Behind the Petricon feature flag.

Summary

Add Petricon, Petrinaut's SVG icon library, as an optional editor icon pack. Icons respond to hover, clicks, and editor state, while the default artwork remains available when Petricon is disabled.

The public Petricon API and /petricon gallery support inspecting individual icons, variants, and motion settings.

petricon--gallery-and-runner-final.mp4

Links

• Ticket FE-1708
• Ticket FE-1706
• Docs Visual settings
• Docs Petricon architecture

Blocked by

• #9695: Icon-pack support

Changes

• Persist the Petricon preference and supply icons through the design-system provider, including portals and fallback icons
• Add named exports, variable stroke weights, outline and filled variants, state transitions, and drawing controls
• Animate the running person on hover or keyboard focus and make it jump on click
• Respect reduced-motion preferences and the editor's Animations setting
• Add the searchable gallery, live inspector, modeling studies, and Storybook examples
• Document the API and editor integration, with a Petrinaut patch changeset

Known issues

• The visual-settings guide still needs refreshed screenshots of the Petricon preference and affected editor controls

Next steps

• Extract a shared ds-icons package and document it on hash.design, as agreed for follow-up
• Check icon alignment and weights against the new typography and design-system components, following Alex's feedback

Test coverage

• All 47 focused icon, cube-projection, and diagnostics tests passed, including nested provider inheritance, uninterrupted cube turns, runner replay, motion opt-outs, and explicit action loops
• All 20 Petrinaut and website build, unit-test, type-check, and lint tasks passed locally
• The architecture structure check and documentation build passed
• Browser checks verified runner hover, click, focus, and Motion off; cube edge visibility; drawing progress; and reduced-motion scrolling
• The recorded gallery demo completed without console or page errors

How to test

Gallery

• Open the Petricon gallery
• Search for person and select Person Running
• Hover the enlarged icon, then click it to jump
• Turn Motion off and repeat to check that the icon stays still

Editor

• Open an editor and enable Petricon in Settings > Viewport
• Exercise editing, simulation, and AI controls
• Disable Petricon to check that the default icons return

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 15, 2026 4:14pm UTC
petrinaut	Ready	Preview	Sep 15, 2026 4:14pm UTC
petrinaut-docs	Ready	Preview	Sep 15, 2026 4:14pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 15, 2026 4:14pm UTC

[vilkinsons]

I know @alex-e-leon will have thoughts, too, but let's publish this at the top-level as ds-icons under /libs/@hashintel rather than have it live within Petrinaut.

We'd like to aim for visual consistency across our apps, and I'm happy for us to maintain this at a company level.

These should also be documented on the hash.design site (e.g. under a /icons page).

I have interaction design feedback on individual icons and want to make sure they fit with our new typography, but am happy to approve the current version of this merging as an interim step.

[alex-e-leon]

Not to act as a blocker, but thought I should share the main risk with these icons not living in the DS.

Many of the ds components are currently tuned to the alignment and weights of the current (fa) icon set (within the 24px canvas different icons have different baselines which affect their alignment next to text, and depending on tuning can look off centre)

If this icon set has different weights/alignment to fa then it could make icons look off balance - or updates to the ds could introduce regressions if not tested against this icon set.

Happy to see how this new set turns out but would want to address this later

[cursor]

PR Summary

Medium Risk
Broad UI surface area (global icon provider and many animated controls) with a feature flag, but defaults stay on legacy icons; main risk is visual/regression or motion/accessibility edge cases when the pack is enabled.

Overview
Introduces Petricon, an optional animated SVG icon pack for Petrinaut, toggled via a new persisted Petricon (Experimental) viewport setting (enableExperimentalIconPack, off by default). When enabled, ExperimentalIconProvider / PetriconProvider swaps design-system icons through a full replacement pack (including portals), with variable stroke weight, outline/filled variants, hover hints, click action effects, state transitions (sidebar, settings, diagnostics, playback, etc.), and progressive draw controls—while respecting reduced motion and the existing Animations setting.

Adds the public Petricon API (with legacy ExperimentalIcon aliases), Panda keyframes for icon motion, wiring in spots like AiAssistantIcon and gutter checkmarks, plus Storybook catalog/modeling studies and a large Vitest suite.

Ships a marketing /petricon route on the website: searchable collection, live inspector with copyable React snippets, and paired design studies. README and visual-settings docs describe usage and editor behavior.

^{Reviewed by Cursor Bugbot for commit 2c6f4fe. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2c6f4fe. Configure here.}