Skip to content

DESIGN.md

Latest commit

 

History

History
267 lines (237 loc) · 9.84 KB

DESIGN.md

File metadata and controls

267 lines (237 loc) · 9.84 KB
Raw
version alpha
name GitHub @ CSI Primer
description A focused, content-first GitHub resource hub built with Primer.
colors
primary on-primary accent-muted canvas canvas-muted foreground foreground-muted border success attention danger done
#0969DA
#FFFFFF
#DDF4FF
#FFFFFF
#F6F8FA
#1F2328
#59636E
#D1D9E0
#1A7F37
#9A6700
#D1242F
#8250DF
typography
page-title section-title body ui metadata
fontFamily fontSize fontWeight lineHeight letterSpacing
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
2rem
600
1.5
-0.02em
fontFamily fontSize fontWeight lineHeight
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
1.25rem
600
1.6
fontFamily fontSize fontWeight lineHeight
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
1rem
400
1.5
fontFamily fontSize fontWeight lineHeight
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
0.875rem
400
1.4285
fontFamily fontSize fontWeight lineHeight
-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif
0.75rem
400
1.6666
rounded
small medium large full
3px
6px
12px
9999px
spacing
xsmall small medium large xlarge section
4px
8px
16px
24px
32px
64px
components
primary-action navigation-active callout content-surface metadata divider status-success status-attention status-danger status-done
backgroundColor textColor typography rounded padding
{colors.primary}
{colors.on-primary}
{typography.ui}
{rounded.medium}
8px 12px
backgroundColor textColor typography rounded padding
{colors.accent-muted}
{colors.primary}
{typography.ui}
{rounded.medium}
8px 12px
backgroundColor textColor typography rounded padding
{colors.accent-muted}
{colors.foreground}
{typography.body}
{rounded.medium}
16px
backgroundColor textColor typography rounded padding
{colors.canvas}
{colors.foreground}
{typography.body}
{rounded.large}
16px
textColor typography
{colors.foreground-muted}
{typography.metadata}
backgroundColor height
{colors.border}
1px
backgroundColor textColor typography rounded padding
{colors.canvas-muted}
{colors.success}
{typography.ui}
{rounded.full}
4px 8px
backgroundColor textColor typography rounded padding
{colors.canvas-muted}
{colors.attention}
{typography.ui}
{rounded.full}
4px 8px
backgroundColor textColor typography rounded padding
{colors.canvas-muted}
{colors.danger}
{typography.ui}
{rounded.full}
4px 8px
backgroundColor textColor typography rounded padding
{colors.canvas-muted}
{colors.done}
{typography.ui}
{rounded.full}
4px 8px

Overview

GitHub @ CSI is a focused documentation and resource experience, not a marketing microsite. It should feel immediately familiar to people who use GitHub: restrained, information-dense, readable, and predictable.

Primer is the design authority. Use Primer React for supported interactive components, Primer Primitives for semantic design tokens, and Octicons for interface iconography. Project CSS exists only to compose the README-driven page shell and content patterns that Primer does not provide.

The YAML values above are light-mode references for tools that consume the DESIGN.md format. Runtime code must use Primer's functional CSS variables so the same roles adapt correctly across light and dark themes.

Colors

Use functional color roles such as --bgColor-default, --bgColor-muted, --fgColor-default, --fgColor-muted, --fgColor-accent, --borderColor-default, and --focus-outlineColor. Never use Primer base color scales directly.

  • Default and muted neutrals carry almost all surfaces and text.
  • Accent blue is reserved for links, focus, selected navigation, and primary informational actions. It is not decorative.
  • Success, attention, danger, and done colors communicate state. Pair color with text or an Octicon; never communicate status with color alone.
  • Emphasis backgrounds must use the matching --fgColor-onEmphasis text role.
  • All patterns must work in both the light and dark Primer themes.
  • The dark GitHub mark circle is the only fixed brand-color exception.

Follow Primer's color usage guidance when a new semantic role is needed.

Typography

Use Primer's system font stacks and functional typography variables. Markdown body copy uses the large body style; controls use medium body; metadata and helper text use small body sparingly.

  • Keep paragraphs left aligned and ragged right.
  • Keep prose around 80 characters per line. Do not let the main reading column expand simply because the viewport is wide.
  • Use weight and spacing for hierarchy before color.
  • Page titles use Primer title-large on regular/wide viewports and title-medium on narrow viewports.
  • Section titles use Primer title-medium. UI labels use semibold medium or small body styles.
  • Centering is limited to the Microsoft/GitHub logo lockup. Resource prose, page headings, tables, and navigation remain left aligned.

Follow Primer's typography guidance.

Layout

Use a calm full-page layout capped at Primer's 1280px xlarge breakpoint. Content padding is 16px below xlarge and 24px at xlarge and above.

  • Regular and wide viewports use three regions: local navigation, the main reading column, and an auxiliary on-page table of contents.
  • When all three regions do not fit, remove the auxiliary TOC first.
  • Narrow viewports use one content column. Primary page navigation becomes a horizontally scrollable local-navigation row and the TOC becomes a disclosure above the article.
  • The reading column, not side regions, receives remaining width.
  • Use Primer breakpoints: 768px for narrow/regular behavior, 1012px for multi-column adjustments, 1280px for xlarge content padding, and 1400px only when a wide-only refinement is necessary.
  • Preserve functionality at every viewport. Do not hide the only path to an action or resource.

Follow Primer's layout guidance.

Elevation & Depth

The interface is border-first and nearly flat.

  • Use --borderColor-default or --borderColor-muted to separate regions.
  • Use --bgColor-muted for subtle grouping.
  • Use Primer resting shadows only for media or a genuinely raised surface.
  • Do not add shadows to routine navigation, tables, callouts, or page sections.
  • Avoid decorative gradients and glass effects. Hierarchy should remain clear without them.

Shapes

  • Use Primer's 6px medium radius for controls, active navigation, callouts, and compact containers.
  • Use the 12px large radius only for prominent media or feature surfaces.
  • Use the full radius only for pills, labels, status badges, the active navigation indicator, and the circular GitHub brand mark.
  • Use 1px borders by default. Thicker borders are reserved for focus or a meaningful callout edge.
  • Do not invent a new radius for an isolated component.

Components

  • Prefer a Primer React component whenever it matches the interaction. Preserve its documented variants, sizing, focus behavior, and semantics.
  • Use Octicons through @primer/octicons-react. Do not draw custom interface SVGs or use emoji as control icons.
  • Navigation has clear current-page state via aria-current, accent text, a muted accent background, and an additional non-color indicator.
  • Buttons and links retain Primer hover, active, focus-visible, disabled, and loading states. External links include an external-link Octicon.
  • Tables remain semantic tables, use borders rather than card shadows, and scroll horizontally when they cannot fit a narrow viewport.
  • Markdown callouts use a muted semantic background, matching border, and a strong leading edge. They are not interchangeable decorative cards.
  • Images retain their natural aspect ratio, never upscale beyond the content region, and use a large radius only when presented as feature media.
  • Motion is functional and brief. Honor prefers-reduced-motion.

Use Primer's component catalog and accessibility guidance before creating custom interaction patterns.

Do's and Don'ts

Do

  • Read this file before changing UI, CSS, layout, responsive behavior, or visual components.
  • Reuse semantic Primer variables and existing project patterns.
  • Review every UI change in light and dark modes at narrow, regular, and wide widths.
  • Preserve visible focus, keyboard navigation, semantic headings, descriptive links, and reduced-motion support.
  • Keep README content readable on GitHub as well as on GitHub Pages.

Don't

  • Introduce another component library, icon set, utility-CSS framework, or parallel token system.
  • Hard-code light-mode colors where a Primer functional token exists.
  • Use base color scales directly or depend on color alone for meaning.
  • Put every section in a card, add decorative gradients, or use shadows as the primary hierarchy mechanism.
  • center body copy, exceed the readable line length, stretch images, or remove functionality at narrow widths.
  • Override Primer component internals when a documented prop or variant can express the intended result.

This file follows the DESIGN.md format: tokens are machine-readable constraints and the prose explains how those roles apply to this repository.