Hop
8115847b32
Hop-State: A_06FN45YJ09WC2QFGJM27VE8 Hop-Proposal: R_06FN45WVVTHC245S2BK503G Hop-Task: T_06FN3MVGY3MT82ESQ89BND0 Hop-Attempt: AT_06FN3MVGY092BFA5MR9C7EG
65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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.
|
|
|