maka/docs/astryx-alignment-inventory.md

<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->

> **Superseded for file-level coverage:** see [astryx-surface-file-inventory.md](./astryx-surface-file-inventory.md) (one row per product surface file). This document remains the family-level wiki map and fix log from the first alignment pass.

# Astryx alignment inventory

Maps [Astryx wiki](https://github.com/facebook/astryx/wiki) conventions onto
Maka product surfaces. Severity: **blocker** (raw control when an Astryx twin
exists / broken hierarchy) · **reimplementation** (a public `@maka/ui` export
shadows a shipped Astryx component — a review signal, not proof) · **polish**
(off-scale px, density).

## Wiki smell checklist (searchable)

| Area | Smell | Prefer |
|------|-------|--------|
| Design · spacing | Off-grid `px` not on `--space-*` | Spacing tokens |
| Design · size | Fixed control height ≠ 28 / 32 / 36 | `size` / density props |
| Design · radius | Nested radii not `outer − gap` | Role radii |
| Design · elevation | Raw `box-shadow` / magic z-index | Elevation tokens |
| API · Use the System | Raw `<button>` / `<input>` / `<select>` with Astryx twin | `Button`, `TextInput`, `Selector`, `List`/`Item`, `EmptyState`, `Dialog`, `ToggleButton`, `Collapsible`, `SegmentedControl` |
| API · Use the System | Public `@maka/ui` export whose name shadows a shipped Astryx component (defined locally, not a re-export) | Re-export the Astryx component, or confirm the local one is intentional |
| Theming | One-off hex for ladder roles | Bridge + product tokens |
| Container padding | Product padding fighting `--container-padding-*` | Let Card/Section/Layout own inset |

## Surface families

### Settings shell
| Surface | Fit | Gaps | Status |
|---------|-----|------|--------|
| `SettingsPage` / `SettingsSection` | High — Heading/Text/HStack open-row idiom | Kit uses `div`+grid (documented) for minmax column | already aligned |
| Settings modal / route header | High — Dialog patterns | — | already aligned |
| Settings rows / expandable | Medium | Product CSS for row chrome | polish |

### Settings pages
| Surface | Gaps | Status |
|---------|------|--------|
| General, Appearance, Data, Providers, Bot, Memory, Permission, Health, About, Usage, Web search, Projects, Subagent, Daily review | Primary actions mostly Astryx `Button`; EmptyState where needed | already aligned |
| Provider catalog / bot overview | `Item` rows | already aligned |

### Module hubs
| Surface | Gaps | Status |
|---------|------|--------|
| `ModulePage` (Layout/Header/Content/Panel) | Vendor layout | already aligned |
| Skills / MCP / Scheduled tasks / Daily review | EmptyState + List + Toolbar | already aligned |
| Module list skeleton rows | `min-height: 42px` off rhythm (not page-bar) | **fixed → 36** |

### Shell / chat chrome
| Surface | Gaps | Status |
|---------|------|--------|
| App shell / session list | SideNav | intentional raw siblings where nested button forbidden |
| Composer | Raw hint/cancel buttons | **fixed → Button** |
| Workbar tabs | Raw `role=tab` + dnd-kit | intentional (dnd + tablist; close is IconButton) |
| Workbar tool picker | Product-authored menu semantics and row chrome | **fixed → List + ListItem** |
| Inspector failed filter | Raw toggle | **fixed → ToggleButton** |
| Plan execution panel | Raw expand toggle | **fixed → Collapsible** |
| Titlebar identity | BreadcrumbItem | already aligned |

### Dialogs / overlays
| Surface | Gaps | Status |
|---------|------|--------|
| External session import | Raw source + row buttons | **fixed → SegmentedControl + Item** |
| Session rename / command palette | Dialog/Astryx | already aligned |

### Panels
| Surface | Gaps | Status |
|---------|------|--------|
| Task ledger | Row min-heights 30/34 | **fixed → 32** |
| Quote / prompt rail chips | Raw expand/remove | polish (chip hit geometry) |

## Fixed in this pass
- Control-height rhythm: task ledger rows/triggers and module list skeleton rows.
- Composer no-model / revision cancel → Astryx `Button`.
- Inspector failed-only filter → Astryx `ToggleButton`.
- External import source + session pick → `SegmentedControl` / `Item`.
- Plan execution expand → Astryx `Collapsible`.
- Workbar tool picker → Astryx `List` + `ListItem`; visible descriptions and native row interaction.

## Remaining polish (non-blocker)
- Quote chips / prompt-rail ticks stay product-shaped hit targets.
- Workbar tab strip stays custom for dnd-kit + `role=tab`.
- Nested button prohibition on SideNavItem endContent (documented intentional).