# openxet design system Version 1 · 2026-10-24 · Applies to openxet.com, its documentation, hosted onboarding, and the optional self-service UI. This is the canonical design reference for humans and coding agents. The product design and accepted ADRs remain authoritative for capabilities, architecture and security. This system turns a first visit into understanding, a successful first task, and a reason to return. Visual polish supports that sequence. Trust is earned by working examples, honest status, useful feedback and reliable behavior. ## Overview ### The promise and the first understanding **openxet stores large files and reuses the parts it already has when you upload a new version.** It is open-source storage based on the Xet protocol. Models, datasets and build artifacts are examples, not the limits of the product. Explain in this order: 1. A person changes a large file. 2. Much of the file can remain the same. 3. openxet recognizes those parts, so they do not need uploading again. 4. This is called deduplication. The files people use remain complete files. 5. People can use the hosted service, operate their own installation, or embed the storage in another product, subject to the current availability below. The first **aha** is “I can keep the whole file while uploading less.” It must be visible above or immediately below the fold, require no account, and work as a still diagram. A technical explanation is available one click deeper. ### Personality Calm, capable, open and considerate. Use light mineral surfaces, dark blue ink, precise type, and one useful illustration. The distinctive element is a pair of file-version strips: unchanged pieces line up; one new piece has a warm highlight. It represents the product instead of decorating it. Keep the existing lowercase name and four-part symbol. Refine its color and spacing; do not invent a new logo in an unrelated feature change. Do not borrow Hugging Face's logo, illustrations, customer claims or visual identity. Credit the Xet protocol and link to upstream explanations. Three directions were considered: a dark terminal-led page, an infrastructure blueprint, and a light explanation-led page. Choose the last: it welcomes less technical readers and gives real product evidence room to breathe. Terminals and architecture diagrams belong after the explanation. ### Stakeholders and the decisions they make | Stakeholder | Question the site must answer | Evidence / destination | Next action | |---|---|---|---| | Newcomer | What does it do, in words I know? | Hero + file-version diagram | Understand the example | | Researcher, engineer, data practitioner | Will it fit how I upload and download? | Tool compatibility + tested quickstart | Try a supported workflow | | Self-hoster / operator | Can I install, maintain and recover it? | Configuration, backends, upgrades, recovery, benchmarks | Run the storage-only quickstart today | | Platform builder / aqora | Can I fit this into my product and permissions? | APIs, authorization seams, tenancy, optional UI | Read integration and architecture references | | Security reviewer / data owner | Can I check the boundaries and evidence? | Security tests, private disclosure, design and ADRs | Review the controls | | Budget owner / procurement | What changes in cost, and what are the obligations? | Measured bytes, cost assumptions; pricing and terms at launch | Evaluate the deployment option | | Contributor / maintainer | Can I understand and improve it? | Source, governance, roadmap, contribution guide | Find a concrete contribution | | Agent acting for any of these | What works, how do I call it, how do I recover? | Markdown, llms.txt, schemas, exits, scoped authority | Execute an authorized task | Human and agent are interaction modes across all roles. Do not force a “human or agent?” choice at the front door. They receive the same facts and availability; each has a suitable interface. Buyers and reviewers are often different people from the person doing the first upload. ### Devices, environments and motivations Design for the task and situation, not a separate visual brand for every persona. The same person can move through several of these scenarios in a day. | Setting | Likely motivation / constraint | Required response | |---|---|---| | Phone, arriving from a shared link | Understand quickly; cannot comfortably install a server | Short explanation, readable diagram, easy waitlist, a durable quickstart link; no terminal interaction required | | Tablet or touch laptop | Evaluate options, read examples, show a colleague | Touch-sized controls, responsive comparisons, no hover-only information or drag-only interactions | | Desktop browser beside a terminal | Try the product with minimal context switching | Exact commands, prerequisites, copy without prompts, expected output, links to recovery steps | | Notebook / research workstation | Move a dataset or checkpoint without changing a research workflow | Version-specific Python/client examples and honest large-file behavior; keep examples useful outside ML too | | Slow mobile connection or unreliable Wi-Fi | Decide whether to trust the product before investing time | Small static page, fonts that fall back, useful content before JS, retained form input, explicit retry state | | Corporate proxy, VPN or restricted script/CDN policy | Evaluate or deploy within existing constraints | Self-hosted assets, native HTML forms, no third-party font/widget dependency; document service endpoint requirements | | Keyboard, screen reader, low vision or reduced motion | Complete the same task independently | Semantic order, labels, text equivalents, zoom/reflow, strong focus, reduced motion and error summaries; no separate degraded mode | | Shared workstation, screen share or public demo | Show the product without leaking private resources | Examples contain no secrets; hide/reveal credentials deliberately in future app; no private receipt in analytics or screenshots | | Operator on a private network or air-gapped system | Install, inspect and recover without access to hosted tools | Downloadable/versioned docs and native CLI; distinguish internet prerequisites from offline operation; waitlist is optional | | Platform product team | Assess how storage fits existing naming, identity and UI | Explain supported seams and permission contracts; the platform's own brand need not inherit openxet's marketing layout | | Budget/security review circulated internally | Build a defensible recommendation, often without running code | Stable deep links, printable/readable evidence, dated benchmarks, explicit current/planned status and named maintainers | | Agent in terminal, notebook or CI | Execute an authorized task unattended | Current Markdown, schemas, stable errors/exits, explicit inputs and versions; no interactive-only prerequisite or assumed browser login | | Browser-controlling agent | Navigate the same public experience a person uses | Semantic control names, labels, status text and ordinary links; no canvas-only content, misleading disabled actions or hidden agent instructions | | Human delegates then returns later | Preserve intent and review the result | Share goal/resource/scope/expected result without secrets; future app attributes actor, shows pending approval and provides a durable result | Use the right **next step for the context** without fingerprinting visitors: all useful paths remain visible and user-chosen. Do not infer skill, disability, budget or role from device size. A mobile practitioner can still read every technical reference; a desktop beginner still sees the plain explanation. When a task must continue elsewhere, offer a stable link or credential-free instruction block. Never put tokens, email addresses, private repository names or cancellation receipts in share URLs, page titles, telemetry or screenshot fixtures. Do not silently copy, launch a terminal, download executable code, subscribe an address or authorize an agent on page load. For a signed-out/stale session, preserve only non-sensitive intent and return the visitor after external sign-in. For cross-device setup, obtain credentials again through the approved identity flow. A public marketing page never needs to know the visitor's identity to explain the product. ### Availability and launch states The user requested a page designed for the final hosted product, with sign-up disabled and a real waitlist now. Express the intended product coherently, then state availability next to the action. Do not make every section a roadmap. | State | Primary action | Identity / pricing | Technical truth | |---|---|---|---| | **Current: waitlist** | Join the waitlist → `/waitlist/` | No active hosted sign-up, sign-in or checkout; no invented prices | M1 storage-only server/client works; Hub/Git and hosted service remain planned | | Hosted launch | Start free → `https://app.openxet.com/signup` | External identity provider; published limits, pricing and terms | Enable only after the real onboarding and stock-client tests pass | | Returning hosted user | Sign in → `https://app.openxet.com/signin` | Same external identity and granted scopes | Return to the user's selected workspace | | Service problem | Status and recovery action | Preserve inputs and authentication context safely | Never imply a successful write before acknowledgement | The app subdomain and path names are a **design decision for future routing**, not an assertion that DNS or endpoints exist. No live link goes to these routes before they work. The header reserves a secondary sign-in position at desktop; in waitlist mode replace it with a useful GitHub/docs link instead of a dead button. Future `/signup` and `/signin` aliases on the marketing origin should redirect only after launch. Pricing appears in navigation only when publishable. ### Information architecture Current navigation: **How it works · Hosting · Docs · GitHub · Join the waitlist**. Keep it short. On mobile, show the brand and waitlist action with a keyboard accessible disclosure for the remaining links; do not hide essential paths. | Destination | Job | Search intent | Present implementation | |---|---|---|---| | `/` | Explain value, demonstrate reuse, route the visitor | open-source large-file storage; Xet storage | Homepage | | `/#how-it-works` | Make the mechanism understandable | how file deduplication works | Explanation and example; preserve old `#dedup` links | | `/#hosting` | Explain hosted, self-hosted and embedded choices | hosted or self-hosted Xet | Honest availability beside each option; preserve `#hosted` | | `/waitlist/` | Save a request for hosted launch contact | openxet early access | One-field form + privacy + confirmed receipt | | `/docs/` | Accomplish a real task | openxet documentation | mdBook, current commands and compatibility | | `/about/` | Establish who builds it and how to participate | openxet project / contact | Maintainer, source, governance, feedback and disclosure links | | `/privacy/` | Explain website/waitlist data handling | openxet privacy | Factual current practices, no speculative certifications | | `/llms.txt` | Find authoritative machine-readable material | Agent discovery | Generated from the same docs navigation | Future dedicated `/self-host/`, `/integrate/`, `/security/`, `/pricing/` and `/blog/` pages are justified by distinct content and visitor tasks, not keyword counts. Until that content exists, link directly to useful docs. Do not publish empty landing pages. Blog posts need an author, date, original example, technical review and related next step; use the editorial backlog in the research note. ### Homepage sequence and working copy | Section | Question answered | Content / behavior | |---|---|---| | Hero | What is this? | **Large files. Lighter uploads.** Supporting text names storage and explains reuse. Hosted waitlist status sits beside CTA. | | File-version illustration | Why should I care? | Show a previously stored file and its edited version; distinguish reused and new parts with labels as well as color. | | Explanation | How does it work? | Three real steps: split into parts, recognize existing parts, upload new parts. Explain “chunks” after “parts.” | | Deployment choices | Where does my data live? | Hosted service (waitlist), own infrastructure (quickstart), own product (integration docs). No fake cloud availability. | | Familiar tools and agents | How will I use it? | Separate available `openxet` / `hf_xet` flows from planned Hub/Git/MCP. Link exact current references. | | Evidence | Why trust it? | Apache-2.0 source, reference-file checks, real-client tests, measured benchmarks and public decisions. | | Practical questions | Is this right for me? | Workloads, variable savings, independence from Hugging Face, release status and pricing availability. | | Final action | What now? | Repeat the waitlist action; offer a direct self-host quickstart. | Desktop composition: ```text openxet How it works Hosting Docs GitHub [Join the waitlist] Large files. Previous file [A][B][C][D][E][F][G][H] Lighter uploads. Updated file [A][B][+][D][E][F][G][H] Plain explanation. 7 parts reused · 1 new part to upload [Join the waitlist] [See how] Illustrative example · change a part Hosted service coming soon. Same file to work with. Less to send. explanation → hosting → tools → evidence → FAQ → CTA ``` On mobile: headline → explanation → actions/status → illustration → remaining sections. Avoid forcing a large artwork above the reason to use the product. ## Colors Use semantic CSS variables, never ad hoc colors in a component. These are the normative values. Functional colors carry stable meanings; new/changed data is amber, interaction is blue, success is green, failure is red. ```yaml colors: canvas: "#F5F7FB" surface: "#FFFFFF" ink: "#142238" muted: "#526079" primary: "#304BCE" primary-hover: "#253DAE" primary-soft: "#E8EDFF" border: "#D3DBEA" control-border: "#77859C" new-data: "#F5CF6B" success: "#176843" danger: "#A12532" dark-canvas: "#101A2B" dark-surface: "#17243A" dark-ink: "#EDF2FB" dark-muted: "#B2BCD0" dark-primary: "#A5B7FF" dark-primary-hover: "#C0CCFF" dark-primary-soft: "#26365A" dark-border: "#394963" dark-control-border: "#8394AF" dark-success: "#8DD8B0" dark-danger: "#FFADB8" ``` The page is mainly canvas/surface and ink. Blue identifies actions and selected content. Amber occupies only the changed file pieces and their legend; never use it as unreadable text on white. Primary buttons use white text in light mode and dark ink on the lighter blue in dark mode. Use control-border for an input boundary that must be perceivable; the quieter border is for separators. Default to system theme, preserve a deliberately chosen docs theme, and check both. Never rely on red/green, opacity alone, or hover to express state. Forced colors must preserve control boundaries and the changed-part labels. ## Typography | Role | Family | Size / line height | Weight / tracking | |---|---|---|---| | Wordmark | Manrope | 24px / 1.1 | 750 / -0.04em | | Hero | Manrope | clamp(44px, 5.4vw, 76px) / 1.04 | 650 / -0.045em | | Section heading | Manrope | clamp(30px, 3.5vw, 44px) / 1.15 | 650 / -0.035em | | Component heading | Manrope | 22px / 1.25 | 650 / -0.02em | | Lead | IBM Plex Sans | clamp(18px, 1.6vw, 21px) / 1.55 | 400 / normal | | Body | IBM Plex Sans | 17px / 1.65 | 400 / normal | | Controls / navigation | IBM Plex Sans | 15–16px / 1.35 | 500–600 / normal | | Captions / metadata | IBM Plex Sans | 14px / 1.5 | 400–500 / normal | | Code / file data | IBM Plex Mono | 13–14px / 1.6 | 400 / normal | Use rem units in implementation, assuming a 16px browser default; never prevent zoom. Body text is at least 16px on mobile. Prose width is 60–68 characters; hero copy 42–48 characters. Headings use sentence case. Reserve uppercase for short diagram labels; do not turn every section label into an eyebrow. Self-host Latin WOFF2 subsets from the official font distribution with license files, `font-display: swap`, and system fallbacks. Only preload a font used above the fold. Do not send visitors to a font CDN. Fall back to system sans and monospace without hiding text or breaking layout. Use tabular numbers for metrics, never monospace for long paragraphs. ## Layout ```yaml spacing: xs: 4px sm: 8px md: 12px base: 16px lg: 24px xl: 32px 2xl: 48px 3xl: 64px 4xl: 96px 5xl: 128px layout: page-max: 1200px reading-max: 680px form-max: 480px mobile-gutter: 20px desktop-gutter: 32px section-gap: "clamp(64px, 8vw, 112px)" ``` Use a two-column hero above 960px, a single column below it. Use a three-column deployment choice group only when all choices fit comfortably; collapse by 768px. At 320px, no horizontal page scrolling, clipped controls or tiny text. Code blocks may scroll horizontally within a labeled region. Use alignment to establish hierarchy. Group content about the same decision; do not put every sentence in a card. Numbers signify a real process, not a decorative layout. Keep sticky navigation small, and use scroll margins so it does not cover headings or focused controls. ## Elevation & Depth Default surfaces have no shadow. Use a 1px separator for ordinary groupings. The hero's file workspace can use `0 16px 48px rgb(20 34 56 / 7%)`; this is the single elevated object. Dialogs, when needed in the future app, use `0 16px 48px rgb(20 34 56 / 18%)`. No glow, glass blur, background particles, floating decorative panels or scroll parallax. Do not apply hover elevation to something that is not clickable. ## Shapes ```yaml rounded: small: 4px control: 8px panel: 16px large-panel: 24px ``` File parts use 4–6px corners. Controls use 8px corners. Rounded pills are only for short status labels. Use a consistent 20px icon box, 1.75px stroke and round joins. Icons accompany meaningful text unless their accessible name is unambiguous. Inline SVG and CSS diagrams are preferred over decorative raster images. Provide a 1200×630 social image matching the current page and status. ## Components ### Buttons and links Primary action: blue fill, at least 44px high (48px on principal forms), 16px horizontal padding minimum, semibold label. Secondary: surface with visible border. Text links inside prose are underlined; navigation links may use an underline on hover/focus. An arrow is optional and decorative. Every action has default, hover, focus-visible, pressed, pending, disabled and error behavior where relevant. Focus uses a 3px primary outline and 3px offset, with a contrasting gap. Pending buttons retain their width and say what is happening. Never disable a form just because the user has not entered data; validate on submit. Disable only during an in-flight duplicate action. Use `` to navigate and `