Hop
8115847b32
Hop-State: A_06FN45YJ09WC2QFGJM27VE8 Hop-Proposal: R_06FN45WVVTHC245S2BK503G Hop-Task: T_06FN3MVGY3MT82ESQ89BND0 Hop-Attempt: AT_06FN3MVGY092BFA5MR9C7EG
2.5 KiB
ADR 0002: Preserve Gitea's design and replace its collaboration semantics
- Status: Accepted
- Date: 2026-07-11
Context
HopWeb needs to become Hop-native without spending early product effort on a new visual shell or maintaining broad Gitea template forks. Gitea already has a coherent, accessible component system and familiar repository navigation.
The first product distinction is conceptual rather than visual. Hop users work with tasks, attempts, checkpoints, proposals, evidence, and accepted outcomes. Gitea exposes closely related infrastructure as issues, branches, commits, pull requests, Actions, and merges.
Decision
Keep Gitea's existing layout, typography, color, spacing, icons, responsive behavior, and component states unchanged.
Load a small same-origin semantic adapter through Gitea's supported custom footer template. The adapter changes visible labels and matching accessibility metadata while preserving the underlying routes and behavior:
| Gitea element | Hop meaning |
|---|---|
| Code | Files |
| Issues | Tasks |
| Branches | Attempts |
| Commits | Checkpoints |
| Pull Requests | Proposals |
| Actions | Evidence |
| Merge Pull Request | Accept Proposal |
On repository home pages, add a compact Hop workflow summary using Gitea's
existing sidebar classes and the live navigation links and counts already
rendered by Gitea. Do not add custom CSS.
Set the application name to Hop, while retaining Gitea attribution and its
standard administrative and Git compatibility surfaces.
Consequences
- Existing Gitea behavior, responsiveness, themes, and accessibility remain available.
- The first Hop experience ships without a deep template fork.
- URLs and APIs remain Gitea-compatible even when their visible names change.
- DOM selectors and English labels are version-sensitive and require a smoke test when upgrading Gitea.
- As Hop gains distinct task and state behavior, individual semantic elements can move from adapted Gitea routes to native server-backed routes without a simultaneous visual redesign.
Guardrails
- Do not add CSS to the semantic adapter.
- Never rename an element unless its behavior is meaningfully compatible with the corresponding Hop concept.
- Keep accessible names and tooltips synchronized with visible labels.
- Scope text replacement to navigation, headings, menus, labels, breadcrumbs, and buttons. Never rewrite repository content or user-authored prose.
- Verify the adapter against the pinned Gitea version before every upgrade.