Shared packages and interface design
Common
Shared interfaces with clear tasks and native behavior.
Common supplies shared typography, brand assets, native controls and page compositions for EggyByte products. Pure preference values, browser binding, Svelte adaptation and styles have separate public entries. Products import what they need and retain content, business state, permissions and actual operations.
Keep the same task coherent across pages Collections, forms and result content share a stable content axis, native controls and language preferences. Each product still defines its facts and actions, allowing users to continue the current task after changing language or window size.
Share presentation; keep product decisions local
The public package identity is @eggybyte/common. It supplies typography and spacing, fixed brand assets, native controls, page frames and common content compositions. Projects supply meaningful copy, business state, permitted operations and actual navigation destinations.
A resource row, for example, keeps an object’s name, facts and actions together. It does not infer permissions from a status label or invent a delete or retry operation. An outcome presents the result and necessary facts before any next steps that the product actually supplies. Visual consistency therefore preserves business behavior.
Choose an entry and own its lifecycle
Use preferences when only locale or appearance resolution is needed: its inputs and outputs are pure values, with no browser operations. Establish browser binding explicitly when a page should follow those preferences. Svelte components adapt that same binding rather than creating another preference owner.
The application root owns the binding, chooses initialization and cleans it up on departure. Import styles.css separately for shared styles and local fonts, while the product chooses its content and actions. Select the needed entries; pure value resolution requires neither a browser nor Svelte.
| Entry | Responsibility | Usage boundary |
|---|---|---|
| preferences | Pure values and immutable snapshots | No browser dependency or browser effects |
| browser | Document preferences and observation | Initialize explicitly; root owns cleanup |
| svelte | Adapt the existing binding and compose controls | Use the application’s runtime; no second owner |
| styles.css | Type, spacing and presentation styles | Import explicitly; products decide tasks and actions |
Import the entries you need. Shared presentation does not take over product routes, business state, permissions or actual operations.
Connect shared presentation at the application root
A Common consumer explicitly imports public styles and selects the program entries it needs. Preference calculation stays a pure value operation. When the document must be synchronized, the application root creates one browser binding. The Svelte adapter consumes that same binding rather than creating another owner on each page.
Initialization precedes visible language-dependent content so the document language agrees with the initial text. The original owner disposes of listeners when the application leaves. Product pages supply their own titles, destinations, data and actions. The package does not infer routes from copy or repeat business requests when the language changes.
Select explicit entries
Import styles, pure preferences, browser effects and Svelte adaptation for the actual task. Pure calculations do not acquire hidden environmental effects.
Keep one presentation owner
Initialize and dispose of the document binding at the application root. Components share current values without competing for root attributes.
Compose real business content
Supply complete labels, object facts and actual available actions while retaining a stable content axis and local reading measure.
Organize whole objects and continuous reading
The page frame owns navigation, main content and the skip link. The content region stays stable; article line length and short-task control measures are selected locally. Loading, submission and results do not arbitrarily resize the outer page.
Resource collections place facts side by side on wide screens and reflow the same object on narrow screens. Names, statuses and actions remain associated, with stable control identity. Reading uses continuous headings, paragraphs, lists and tables. An explicit grouping boundary is reserved for settings or choices that genuinely belong to one task.
Change presentation while retaining the task
Locale resolution first accepts a supported explicit stored choice, then finds Chinese or English in browser language order, falling back to Chinese. A formatting locale controls presentation conventions; it does not select financial precision or the time zone for a business date.
The binding synchronously applies document preferences before publishing its current state. A storage failure preserves the in-memory choice. Preference changes do not reset routes, business state or unfinished input. Same-origin applications may read the shared keys at initialization; cross-origin sharing and live synchronization are not promised.
Explain the next step with explicit state, not color alone
A collection distinguishes loading, a successful empty result and a failed read. A mutation may also be pending, definitely rejected or unknown. Common supplies presentation for these distinctions; the business supplies the actual state and permitted next action. A failed screen does not automatically authorize a Retry button.
Known facts remain distinct from the latest observation. After a failed refresh, useful previously read content can remain with its observation scope. Reopening a page does not turn an unknown mutation into one that never happened. Amounts, counts, time zones and precision follow the business definition; language changes their presentation.
| Observation or action | Meaning retained by the page | Business-owned continuation |
|---|---|---|
| Successful empty read | No matching result exists within this query’s observed scope. | Whether to create, change criteria or continue to another page. |
| Unavailable read | This attempt did not obtain a complete observation; old facts and counts do not become zero. | Whether to read again and which original actions remain authorized. |
| Unknown mutation | Retain the original target and input without claiming failure or rollback. | How to query the original identity and when another explicit action is permitted. |
Keep native semantics and observable effects
Links navigate, buttons execute commands and native radios express alternatives. Selecting an option does not itself submit a business operation. Each action retains its description, pending state and real target. Labels, assistance and errors refer to the actual input; icons inside named controls remain decorative.
Verification is organized around complete tasks: operating a resource, configuring and submitting, choosing a sign-in method, and understanding a result. The design requires Chinese and English at wide and narrow widths, local fonts and brand assets, keyboard focus, and retained input and callback counts through preference changes. Render review and behavior proof provide separate evidence; geometry checks alone do not establish visual acceptance.
Review complete tasks across widths and languages
Visual review uses realistic titles, prose, object facts and feedback, with Chinese and English represented in wide and narrow layouts. Check that each object’s name, state and actions stay together, prose remains continuous and complete values wrap without forcing page-level horizontal scrolling.
Behavioral checks observe keyboard focus, native control relationships, unfinished input and actual invocation counts. Language changes may reflow content but must preserve drafts, targets and business state. Geometry checks can reveal overflow; the final visual judgment still requires looking at the completed pages.