Skip to content

refactor(web): extract themed default logo - #309

Merged
ravirajsinh45 merged 3 commits into
Techiebutler:mainfrom
luozejian:refactor/288-themed-default-logo
Sep 2, 2026
Merged

ravirajsinh45 merged 3 commits into
Techiebutler:mainfrom
luozejian:refactor/288-themed-default-logo

Conversation

@luozejian

Copy link
Copy Markdown
Contributor

Summary

  • add a shared ThemedDefaultLogo with icon/full variants, meaningful or decorative accessibility modes, and caller sizing classes
  • render one canonical asset per logo and theme it through data-theme CSS, preserving share-page overrides without loading a hidden second image
  • migrate all six duplicated fallback blocks across sidebar, auth, share password gate, powered-by badge, and branding mocks
  • use the themed fallback when a custom auth logo fails, while allowing a new logo URL to retry

Testing

  • pnpm test — 47 files, 358 tests passed
  • pnpm exec tsc --noEmit --pretty false
  • pnpm build

Closes #288

@ravirajsinh45 ravirajsinh45 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@luozejian thanks for pulling these six duplicated logo blocks into ThemedDefaultLogo, good direction. A few things to fix before merge:

Blocking

  1. CHANGELOG — no entry under [Unreleased]. This fixes a real bug (auth logo fallback never retrying) and changes rendered output in 6 places, so it should be documented per AGENTS.md.
  2. Screenshots — the PR touches visible logo rendering in the sidebar, auth header, share password gate, powered-by badge, and settings previews, but there's no before/after screenshot. Please add them.
  3. Theme filter can be silently overridden — .themed-default-logo's filter lives in @layer components (globals.css:118), and ThemedDefaultLogo merges an open className and forwards style with no guard (themed-default-logo.tsx:37). Any future caller passing a filter-related class or inline style (e.g. className="drop-shadow-sm", style={{filter: 'none'}}) will silently break the dark-theme recolor with no error. Worth excluding style from the forwarded props and either scoping the filter more defensively or documenting the constraint clearly on the component.

Worth a look, not blocking

  • auth-branding-header.tsx's new failedLogo state never retries a URL that recovers after a transient failure (branding-preview.tsx already solves this the same way with a useEffect reset on URL change — could reuse that pattern).
  • The theme-based logo-URL fallback ternary (loginLogoUrl || (theme === 'dark' ? ... : ...)) is now duplicated across auth-branding-header.tsx, share/[token]/page.tsx, and sidebar.tsx — since this PR already touches all three, might be worth extracting alongside the component work.
  • themed-default-logo.test.tsx: the injected <style> tag (line 47) only gets cleaned up if its assertions pass, so a failing test leaks it into later tests in the file.
  • FreeFrameMark in powered-by-badge.tsx is now a dead one-line wrapper — could be inlined at its single call site.

@luozejian

Copy link
Copy Markdown
Contributor Author

@ravirajsinh45
Addressed the review feedback in a follow-up change:

  • added an [Unreleased] / Fixed CHANGELOG entry
  • made the logo filter component-owned: style and srcSet are excluded, caller className is documented as sizing/layout only, and explicit data-theme rules now sit outside Tailwind layers
  • aligned auth image-error reset with the branding preview and added an A → B → A retry regression test
  • extracted and tested the shared branding-logo URL resolver across sidebar, auth, share password gate, and branding preview
  • made the CSS test cleanup unconditional with finally
  • inlined the one-use FreeFrameMark wrapper

Validation:

  • focused tests: 3 files / 15 tests
  • full Vitest: 48 files / 365 tests
  • TypeScript: passed
  • lint: passed (existing warnings only; none in changed files)
  • production build: passed

Screenshots are attached below. The intended visual output is unchanged; the comparisons cover the login/auth header and attribution, the share password gate, and the settings branding/sidebar preview.

Maintainer touch-up on top of the review round, all in the same
direction the branch was already going.

The globals.css comment credited "outside Tailwind's layers" for the
filter's precedence. Tailwind v3 flattens the @tailwind directives at
build time and emits no @layer at-rules, so there is no layer priority to
gain. What actually beats a bare utility is specificity, two selectors
against a utility's one, plus sitting after the utilities @tailwind
emits. That covers bare utilities only: a variant-prefixed one (hover:,
group-hover:, peer-*) is emitted later at equal or higher specificity and
would still win. The comment now says that, so the caller contract is
legible rather than implied.

Dark becomes the unscoped default, matching :root at the top of the same
file. Both rules were attribute-gated, but :root and [data-theme="dark"]
share the dark palette, so a document that never received a data-theme
was painted dark while the logo kept its black ink. Narrow, since the
head script sets the attribute on both its try and catch paths, but it
costs one selector to close and it restores the file's own convention.

style and srcSet were excluded from the props type yet still reached the
img at runtime, because the spread precedes only src, alt, aria-hidden
and className. Pinning both to undefined makes the ownership the JSDoc
claims true without resting on the caller being typechecked.

Three test fixes follow from that. The type-only prop assertion asserted
a literal [true, true] and could not fail under vitest, which strips
types; it is now a render that forces both props past the types and
checks the DOM. The globals.css read was anchored to process.cwd(), the
launching shell's directory rather than vitest's root, so it threw ENOENT
from the repo root; it is anchored to the test file instead. And
"applies the production theme filter despite a later filter class"
over-claimed: .filter-none is one selector and loses on specificity
whatever its position, so the assertions were identical with the class
present, absent or first. Renamed to what it checks, with the rule
scoping now asserted explicitly so an unscoped rule cannot slip back in.

All three mutations verified to fail the suite before this was written.

@ravirajsinh45 ravirajsinh45 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified the pixel claim independently and picked up the remaining small items in 98b6276. CI green on all four jobs. Thanks @luozejian.

@ravirajsinh45
ravirajsinh45 merged commit 5f9b071 into Techiebutler:main Sep 2, 2026
4 checks passed
@ravirajsinh45

Copy link
Copy Markdown
Contributor

@luozejian thanks for the quick turnaround on round 1. Five of the seven items landed cleanly, and rather than send this back for another round we picked up the remaining small ones ourselves and pushed 98b6276 to your branch.

One thing worth flagging first: your comment says "Screenshots are attached below" but nothing came through, so the upload must have failed silently. With no visual evidence to check the change against, we ended up verifying the pixel claim the long way, and that closer look is where the rest of this came from. Worth attaching them next time a PR touches rendered output, since AGENTS.md and the PR template both ask for it.

The good news is that the swap really is pixel-exact, and we confirmed it rather than assuming it. logo-icon.png is RGB(255,255,255) at every pixel with alpha above zero, logo-icon-dark.png is RGB(0,0,0), and their alpha channels are byte-identical, so brightness(0) invert(1) reproduces the white asset exactly. For the lockup, sed 's/#18181b/white/g' logo-full-dark.svg diffs clean against logo-full.svg, and neither file has gradients, strokes or opacity. Every migrated call site keeps its exact class list, and the old .logo-dark = dark / .logo-light = light direction is reproduced correctly at each one. The share password gate also quietly gained an accessible name in light theme that it never had before, which the PR does not claim but is a real improvement.

What changed in 98b6276:

1. The globals.css comment named the wrong mechanism. "Outside Tailwind's layers" does not do anything on Tailwind 3.4: the @tailwind directives are flattened at build time and the output carries no @layer at-rules. What beats a bare utility is specificity, two selectors against one, plus sitting after the emitted utilities. We compiled the real config to check, and that covers bare utilities only. .hover\:drop-shadow-sm:hover (equal specificity, emitted later) and .group:hover .group-hover\:brightness-110 (higher) still win. The comment says that now, which makes the caller contract legible instead of implied.

2. Dark is now the unscoped default. Both rules were attribute-gated, but :root and [data-theme="dark"] share the dark palette at the top of the same file, so a document that never received a data-theme painted dark while the logo kept its black ink. Narrow, since the head script sets the attribute on both its try and its catch path, but one selector closes it and it restores the file's own convention.

3. style and srcSet are now actually dropped. They were omitted from the props type but still reached the <img> at runtime, because the spread precedes only src, alt, aria-hidden and className. Pinning both to undefined makes the JSDoc's ownership claim true without resting on the caller being typechecked.

4. Three test fixes. The prop-restriction test asserted a literal [true, true] equals [true, true], which cannot fail under vitest since types are stripped; it is now a render that forces both props past the types and checks the DOM. The globals.css read was anchored to process.cwd(), which is the launching shell's directory rather than vitest's root, so it threw ENOENT if vitest ran from the repo root. And applies the production theme filter despite a later filter class over-claimed: .filter-none is one selector and loses on specificity whatever its position, so the assertions came out identical with the class present, absent, or first in the sheet. It is renamed to what it checks, and the theme scoping is now asserted explicitly so an unscoped rule cannot slip back in.

Each of those is mutation-checked: revert the runtime strip, delete a CSS rule, or unscope one, and the suite fails.

tsc --noEmit clean, 48 files / 365 tests passing, no new lint warnings, and all four CI jobs green, so this is merged as 5f9b071. Thanks for taking this one on.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(web): extract shared themed default logo

2 participants

⌂ 换网址