@v4/ghost-basketball

Overview

@v4/ghost-basketball is the basketball UI library: the presentational building blocks for schedules, standings, brackets, the Game Centre, the stats hub, and player, coach and team surfaces, built from the ELB – Web – Basketball Figma file (8Jl1miPEIZslMda8jZ8w0C).

It is new UI, not a fork. Unlike ghost-content and ghost-video there is no upstream Ghost file to diff against — none of the file's component ids appear in any Ghost or ELB file — so the preserved-id trap does not apply and fork-diff has nothing to compare. Every bridge names 8Jl1miPEIZslMda8jZ8w0C from birth, with one exception:

• The ECAL schedule picker (the Games page's "Add to calendar" choice) — ecal-all-games, ecal-team-option and ecal-schedule-picker — is built from ELB – Web – EXT (Yqy0zItrtL4UptOVW54wVg, page "Updated E-Cal"), the client's concept file. Its frames carry no Token Studio data, so these three components' theme leaves are INFERRED from the global contract rather than extracted, and their bridges name the EXT file. node packages/token-parser/scripts/check-bridges.mjs accepts it because the file is listed in .claude/manifest.json. (dialog bridges the Basketball file and records the EXT page only as an additional source.)

It is club-only, the @v4/wsc / @v4/eltv model: no domains.json entry and no club.config domain, so /sync-upstream never offers or prunes it. Its registration lines in synced files (Storybook config, the e2e theme-emission spec, the token-parser and ticket scripts, ghost-core's global surface) are single, commented lines so a sync conflict on them is trivial to resolve.

Like the other siblings it composes @v4/ghost-core and @v4/ghost-content (chips, buttons, drop-downs, carousel paddles, pagination, header blocks) rather than re-implementing them. It is purely presentational: the data comes from the Competition Engine through @v4/basketball-app, which maps the engine's views onto these props.

Components

139 components (packages/ghost-basketball/src/components/*, _internal excluded), built leaves first in batches B-1 (atoms) to B-6 (pages) and then the Game Centre, widgets and stats hub. The plan, the per-set inventory and the progress log are .claude/reference/figma/ghost-basketball-plan.md, ghost-basketball-inventory.md and ghost-basketball-progress.md.

src/components/_internal/ holds the private layouts several components share — basketball-page (the page frame), stat-bar, table-scroller, widget-panel — plus two helper modules, hero-widget-column.ts and widget-text.css.ts. Each public component built over one declares it in its manifest's coverage.delegatedThemes.

Entry points

package.json exports 38 keys: the barrel, the stylesheet, ./self-emitted-themes and 35 per-component subpaths.

The per-component subpaths exist so a client module can compose one page or widget without pulling in the package barrel — and with it every component's stylesheet. They began with ./page-team and ./page-all-teams when the teams pages became the package's first consumer in the Next app, and grew with each consumer:

• Pages: ./page-team, ./page-all-teams, ./page-coach, ./page-player, ./page-game-centre, ./page-all-players, ./page-standings, ./page-stats, ./page-games-schedule, ./page-skeleton;
• Widgets (the team and player headers, the article header and the home hero): ./widget-form, ./widget-next-game, ./widget-record, ./widget-list, ./widget-stats, ./widget-points-by-quarter, ./widget-game-situation, ./widget-mvp, ./widget-team-leaders, ./widget-team-comparison, ./widget-next-games, ./widget-versus;
• The rest: ./player-records-table, ./dialog, ./filter-field, ./ecal-schedule-picker, ./game-sticky-bar, ./stat-key, ./player-stats-row, ./player-game-row, ./standings-row, ./game, ./game-score-card, ./header-standings-table, ./stats-hub-table.

A new subpath needs no other wiring: the build emits every component's dist/components/<name>/.

Consumers and the theme part

@v4/basketball-app (every data area, the article header widgets and the home hero), @v4/code-of-conduct (the report screens), apps/web and apps/storybook depend on the package.

In the app the package's component themes are not in the every-page stylesheet. The club emits them as a separate part (createClubThemePart, see @v4/tokens-euro-league):

A route that renders a basketball component must load the part, or the component declares no variables and renders unstyled with nothing failing. A widget added to the home hero must also add its themes (and its children's) to HOME_HERO_THEMES. Why the club theme is emitted in parts is on Theme emission and performance.

Tokens

Ghost 2.0 has no basketball namespace and no team colours, so ghost-core's global surface carries a basketball extension (packages/ghost-core/src/theme/basketball-surface.ts):

• components.basketball.* — Ghost's components.football tree (310 leaves, which the ELB Component/Basketball set mirrors path for path) plus color.card.squadListingCard.teamBackground and color.teamHeader.teamBackground;
• teams.teams.<club>.{primary,secondary,gradient} — the 20 EuroLeague clubs of the ELB Teams set (BASKETBALL_TEAM_KEYS, exported from @v4/ghost-core/theme), keyed exactly as the token parser generates them.

Ghost's defaults there are authored (football's values; every team on Ghost's primary ramp), and @v4/tokens-euro-league resolves the extension direct from the club export (pnpm --filter @v4/tokens-euro-league coverage fails if any leaf stops resolving). Components bind g.components.basketball.* and g.teams.* contract paths, never raw tokens.*.

The design has no colour sets: a component with a ColourWay=Default | Inverse axis takes colourSet default | inverse only, and one without the axis takes no colourSet at all.

How components are built

Every component goes through /generate-from-figma <node url> --package=ghost-basketball, which resolves the component directory, bridge registry, --filter, registrations (including the OWN_THEMES entry), the Storybook folder (stories/ghost-basketball/<category>/, titled Ghost-Basketball/<Category>/<Name>) and the e2e folder (apps/e2e/tests/ghost-basketball/) from the package. Coverage is measured with v4-tokens coverage -c packages/ghost-basketball/src/components -n <name> --write.

Since 7 Nov 2026 the package's stylesheets are precompiled in its build, and each component's theme is emitted with its own stylesheet (@v4/ghost-core's precompile-styles.mjs): a page loads only the themes of the basketball components its route imports, and every part above passes SELF_EMITTED_THEMES so it leaves those out.

Scripts: build (tsc -p tsconfig.build.json, then ../ghost-core/scripts/precompile-styles.mjs, then scripts/check-dist.mjs, which fails when OWN_THEMES and the package's theme modules disagree), dev, test / test:watch, lint, check-types, check-dist. src/package-wiring.test.ts guards the wiring every component depends on: the components.basketball and teams contract paths resolve, the 20 team keys, and the TEST_ID registry's shape.

Utilities

Shared, package-private helpers in src/utils/:

Motion

ELB's motion spec wins. Design delivered the EuroLeague Motion Spec v0.3 on 27 Oct 2026; before it, every motion in this library was code-originated and "awaiting design confirmation". The spec, its rules and how a motion is built and tested are on Motion (rule: .claude/rules/frontend/motion.md; digest: .claude/reference/motion/elb-motion-spec.md; build plan: .claude/plans/elb-motion-spec.md). Where the code and the spec disagree, the spec wins and the change goes through the plan. Values from the spec's later v1.0 report (4 Nov 2026) are already in the tokens, and the basketball page e2e is written against them.

Every animation names its spec pattern in a comment on the rule or hook (// P-CASCADE — first 10 rows, stagger.list). Across 116 files under packages/ghost-basketball/src the patterns in use are:

The rules, as this package applies them

Every one of them follows the rules on Motion: values come from ghost-core's global motion.* contract (durations, easings, staggers and distances — club-overridable, so a tuning pass changes one value), CSS goes through createTransition / createAnimation, only transform and opacity move, the concurrency and cascade budgets hold, entrances play once per visit, and nothing waits for motion. Worth restating here, with this package's own checks:

• Ads, logos (beyond a fade) and repeating blinks are never animated, and colour changes only for state tints.
• Reduced motion is a complete, instant page. Under prefers-reduced-motion: reduce every element of every basketball story reads transition-duration: 0s and animation-name: none (apps/e2e/tests/ghost-basketball/reduced-motion.e2e.ts, generated from the Storybook index); motion-basketball-pages.e2e.ts asserts the page patterns run with their token durations.
• The story suite reads final states (data-motion-final), so a play function never meets a card held at opacity 0 and axe never measures text mid-fade. The e2e never sets it: it is where motion is tested.

Motion utilities

The hooks shared with every package live in @v4/ghost-core/motion (useRevealOnView, useCascade, useFlipReorder, useIndicatorSlide, useCountUp, RollingDigits, useSettle…). This package's own motion utilities in src/utils/:

For the theming model see Theming and colour sets.