> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase23-session02-ui-polish-optional-local-tooling/spec.md). # Session Specification **Session ID**: `phase23-session02-ui-polish-optional-local-tooling` **Phase**: 23 - Non-Hermes Routes, Polish And Closeout **Status**: Complete **Created**: 2026-06-02 **Completed**: 2026-06-02 *** ## 1. Session Overview This session applies the remaining small v2.3 UI polish items that are independent of Hermes feature parity: a skill-card hover sheen on the home and skills surfaces, and desktop sidebar behavior that stays visible and scrollable on short viewports. The work is deliberately narrow; it should not rework the home page, the skills route layout, or the local-agent navigation beyond the source polish. The session also records explicit decisions for optional local tooling. AIOS already contains all ten Hermes file-type art outputs under `src/assets/hermes-art/file-types/`, so regeneration scripts should only be ported if a current regeneration need or owner is confirmed. The optional Claude launch config can be added only with AIOS-specific settings and the current dev command/port, otherwise the deferral must be recorded. This is the natural next Phase 23 session because `phase23-session01-claude-code-agent-route` is complete, while `phase23-session03-non-hermes-parity-documentation-closeout` depends on both Phase 23 Sessions 01 and 02. Completing this session leaves only final validation and documentation closeout. *** ## 2. Objectives 1. Add reduced-motion-safe hover sheen behavior to home and skills cards without layout shift, text overlap, or focus regressions. 2. Update the sidebar desktop behavior so it remains visible and independently scrollable on desktop-height layouts while mobile navigation stays usable. 3. Decide whether to add the optional AIOS launch config, using the current `bun run dev` workflow and dev-server port if added. 4. Record the optional Hermes file-type art regeneration script decision, deferring script ports when existing outputs are sufficient. *** ## 3. Prerequisites ### Required Sessions * [x] `phase23-session01-claude-code-agent-route` - Provides the current Agents sidebar shape and confirms Claude Code routing is already present. * [x] `phase22-session03-setup-wizard-dream-sources-strip` - Provides the current home information architecture and Dream source-strip context. * [x] `phase20-session02-cleanup-parity-signoff` - Provides the Hermes asset parity context and existing file-type art outputs. ### Required Tools/Knowledge * Tailwind CSS 4 and route-scoped CSS conventions in `src/styles.css`. * React 19 component and route conventions. * Existing `SkillCard` home component and inline skills route card markup. * Local sidebar primitive behavior in `src/components/ui/sidebar.tsx`. * Vitest and Testing Library component/route tests. * v2.3 source anchors listed in `.spec_system/PRD/phase_23/PRD_phase_23.md`. ### Environment Requirements * No live Hermes, Claude Code, or asset-generation service is required. * `bun run dev` is the current AIOS dev command. * CONVENTIONS records the local Vite UI port as `127.0.0.1:5189`. * Existing file-type art assets under `src/assets/hermes-art/file-types/` must remain committed outputs, not regenerated during this session. *** ## 4. Scope ### In Scope (MVP) * AI OS users can hover or focus home skill cards - Add a sheen overlay that uses stable dimensions and does not resize card content. * AI OS users can scan skills route cards - Apply equivalent sheen behavior to the inline skills page cards without changing grouping, filters, or ROI controls. * AI OS users can navigate desktop sidebars on short screens - Update the sidebar fixed/sticky behavior so content remains visible and scrollable. * AIOS maintainers get an optional launch-config decision - Add `.claude/launch.json` only if useful for AIOS and configured to the actual dev command/port. * AIOS maintainers get an asset-regeneration decision - Keep `gen-hermes-file-type-art.ts` and `webp-file-type-art.sh` deferred unless a current regeneration need is confirmed. * AIOS reviewers get focused coverage - Add or update tests for card sheen, sidebar scrollability, optional tooling notes, and route smoke behavior. ### Out of Scope (Deferred) * Reworking home or skills page layouts - Reason: this session only ports source polish. * Re-generating Hermes file-type art - Reason: all ten outputs already exist. * Porting asset-regeneration scripts without a current regeneration need - Reason: optional tooling should not create maintenance surface without value. * Hand-editing generated route-tree output - Reason: this session should not add routes. * Adding new heavy visual dependencies or 3D surfaces - Reason: bundle budget and Phase 23 scope only allow lightweight polish. *** ## 5. Technical Approach ### Architecture Keep the polish in existing local surfaces. The home route already delegates skill cards to `src/components/home/skill-card.tsx`, so the home card sheen should live in that component and shared CSS. The skills route still renders its grouped skill cards inline in `src/routes/skills.tsx`, so it needs the same overlay class and markup there unless the implementation extracts a tiny local helper without broad refactor. Place shared animation rules in `src/styles.css` near existing animation utilities. The sheen should be a pointer-events-none absolute element with a paused or one-shot animation, bounded opacity, and a reduced-motion fallback. The animation must not change layout, obscure text, or run continuously while idle. Update sidebar behavior at the narrowest current boundary. AIOS uses a local sidebar primitive, and the desktop sidebar is currently implemented as a fixed container with full viewport height and scrollable content. If the v2.3 sticky classes map more cleanly onto `src/components/ui/sidebar.tsx` than `src/components/app-sidebar.tsx`, implement the AIOS-equivalent behavior in the primitive and test it there. ### Design Patterns * Existing component ownership: Home skill polish belongs to `SkillCard`; skills page polish stays near current route markup. * CSS utility reuse: Shared `.skill-card-sheen` rules avoid duplicating inline animation definitions. * Reduced-motion by design: Motion should pause or disappear for users who prefer reduced motion. * Primitive-level sidebar behavior: Put scroll/sticky mechanics where the current sidebar layout owns them. * Decision records for optional tooling: Implementation notes must capture why tooling was added or deferred. ### Technology Stack * React 19.2.0 for component and route rendering. * TypeScript 6.0.3 for application code. * Tailwind CSS 4.2.1 and semantic CSS custom properties in `src/styles.css`. * TanStack Router 1.170.4 for home and skills route links. * Vitest 4.1.6, happy-dom, and Testing Library for focused tests. * Bun 1.3.14 for package scripts and local dev commands. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- | | `.claude/launch.json` | Optional AIOS launch config if the implementation confirms it is useful and uses port 5189. | \~12 | | `.spec_system/specs/phase23-session02-ui-polish-optional-local-tooling/implementation-notes.md` | Source anchors, optional tooling decisions, smoke results, and deferrals. | \~120 | | `.spec_system/specs/phase23-session02-ui-polish-optional-local-tooling/security-compliance.md` | Security and privacy note for UI-only polish and optional tooling. | \~80 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `src/styles.css` | Add reduced-motion-safe `.skill-card-sheen` keyframes/rules if absent. | \~45 | | `src/components/home/skill-card.tsx` | Add stable sheen overlay to home skill cards. | \~15 | | `src/routes/index.tsx` | Verify home route card usage remains compatible and add smoke assertions only if needed. | \~10 | | `src/routes/skills.tsx` | Add sheen overlay to grouped skills cards without changing filters or ROI controls. | \~20 | | `src/components/ui/sidebar.tsx` | Apply AIOS-equivalent sticky/full-height/scrollable desktop sidebar behavior if needed. | \~20 | | `src/components/app-sidebar.tsx` | Apply sticky/scroll class only if the primitive is not the correct ownership boundary. | \~10 | | `src/components/home/__tests__/skill-card.test.tsx` | Cover sheen markup, link behavior, and stable card content. | \~80 | | `src/routes/__tests__/skills.test.tsx` | Cover sheen markup and existing skills route behavior. | \~40 | | `src/components/ui/__tests__/sidebar.test.tsx` | Cover desktop scroll/sticky class behavior and mobile unchanged behavior. | \~50 | | `src/components/__tests__/app-sidebar.test.tsx` | Cover app-level sidebar class or active navigation behavior if touched. | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Home skill cards include the sheen effect without changing link targets, card metrics, or text layout. * [ ] Skills route cards include the sheen effect without changing filters, grouping, signal labels, or ROI controls. * [ ] Sheen animation respects reduced-motion preferences and does not run as a continuous idle animation. * [ ] Desktop sidebar remains visible and scrollable on short viewport layouts. * [ ] Mobile and narrow viewport navigation remains usable and closes on route change. * [ ] Optional launch config is added with AIOS dev settings or explicitly deferred with rationale. * [ ] Hermes file-type art regeneration scripts are ported only if a current regeneration need is confirmed; otherwise deferral is recorded. ### Testing Requirements * [ ] Home `SkillCard` test written and passing. * [ ] Skills route regression test written or updated and passing. * [ ] Sidebar primitive/app test written or updated and passing. * [ ] Visual or route smoke checks completed for `/`, `/skills`, and a desktop sidebar-height case. * [ ] Focused typecheck/build validation passes or records actionable gaps. ### Non-Functional Requirements * [ ] No new heavy dependencies or large assets are added. * [ ] No private paths, credentials, generated runtime data, or asset-service secrets are introduced. * [ ] UI text remains within cards and controls on mobile and desktop. * [ ] Bundle budget concerns are not worsened by this polish. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Optional tooling decisions are recorded before validation. *** ## 8. Implementation Notes ### Key Considerations * `src/components/home/skill-card.tsx` owns the home skill card; do not patch home route markup when the shared component is the right boundary. * `src/routes/skills.tsx` still has inline grouped card markup and needs its own sheen overlay unless a small local helper is clearly cleaner. * Current `src/components/ui/sidebar.tsx` owns desktop sidebar mechanics; map v2.3's `sticky top-0 h-screen overflow-y-auto` intent to the current AIOS primitive before touching `AppSidebar`. * `.claude/launch.json` is absent in AIOS today. If added, use `bun run dev` and port 5189, not the v2.3 port 8081. * All ten file-type art outputs already exist: `archive.webp`, `audio.webp`, `code.webp`, `data.webp`, `html.webp`, `markdown.webp`, `other.webp`, `pdf.webp`, `text.webp`, and `video.webp`. ### Potential Challenges * Sheen effect obscures text: Mitigate by keeping the overlay behind relative content or in image/header regions and using low opacity. * Motion runs continuously: Mitigate with paused idle animation and `prefers-reduced-motion` handling. * Sidebar primitive class changes affect mobile sheet behavior: Mitigate with focused primitive and app-sidebar tests. * Optional tooling creates stale maintenance surface: Mitigate by documenting deferrals when outputs already exist and no owner is confirmed. ### Relevant Considerations * \[P01] **3D vendor chunk budget**: This session must stay lightweight and add no heavy visual dependencies. * \[P00] **Do not document planned features as implemented**: Optional tooling notes must separate added config from deferred scripts. * \[P02] **Extension payloads and demo labels stay bounded**: UI smoke should avoid changing generated-data behavior or extension payloads. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Hover polish can introduce layout shift, continuous motion, or inaccessible visual overlays. * Sidebar scroll changes can trap content or break mobile navigation close behavior. * Optional tooling can encode the wrong dev port, imply script ownership, or introduce generated-output churn. *** ## 9. Testing Strategy ### Unit Tests * Test `SkillCard` renders its link, status dot, metrics, and sheen overlay. * Test `/skills` continues to map live skills into categories and includes the sheen overlay for rendered cards. * Test sidebar primitive/app classes for desktop full-height scrolling and unchanged mobile behavior where feasible in happy-dom. ### Integration Tests * Run focused component and route suites: `bun run test -- src/components/home/__tests__/skill-card.test.tsx src/routes/__tests__/skills.test.tsx src/components/ui/__tests__/sidebar.test.tsx src/components/__tests__/app-sidebar.test.tsx` * Run typecheck or a targeted build check after code changes. ### Manual Testing * Smoke `/` and `/skills` on desktop and mobile widths. * Check hover/focus card states with normal motion and reduced motion. * Check desktop sidebar behavior on a short-height viewport with enough nav content to require scrolling. ### Edge Cases * No skills detected. * Many skills across multiple categories. * Long skill names. * Reduced-motion preference active. * Mobile sidebar route changes. * Optional launch config absent or present with current AIOS port. *** ## 10. Dependencies ### External Libraries * Tailwind CSS: 4.2.1 * React: 19.2.0 * TanStack Router: 1.170.4 * Vitest: 4.1.6 ### Other Sessions * **Depends on**: `phase23-session01-claude-code-agent-route` * **Depended by**: `phase23-session03-non-hermes-parity-documentation-closeout` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase23-session02-ui-polish-optional-local-tooling/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.