webconsulting-branding

webconsulting 设计系统

来源：https://github.com/dirnbauer/webconsulting-skills

当前的 webconsulting 风格简洁、方正、精准，以内容为主。它通过字体、间距、表面颜色和填充式强调来构建层级。装饰性边框和圆角卡片属于旧版样式。

1. 参考优先级

参考资料相互冲突时，按以下顺序采用：

1. 当前发票界面，用于密集信息、表单、表格和文档层级。
2. 当前内部产品，例如项目跟踪器和 GitLab 主题。
3. 当前公共 webconsulting.at 网站，用于编辑式布局、营销页面和大规模构图。
4. 本规范，用于可复用的设计令牌和实现规则。

如果可以访问实时界面，请先查看。不要仅仅因为旧模式已存在于组件库中，就重新引入它。

2. 不可妥协的视觉规则

• 使用直角：border-radius: 0 和 Tailwind rounded-none。
• 不要为卡片、面板、提示框、按钮、表格或分区添加装饰性边框。
• 使用留白、背景变化、字体粗细、斑马纹行和对齐方式来区分内容。
• 阴影仅用于菜单、对话框和粘性浮层等临时凸显场景。
• 在页眉顶部保留一条品牌通知或强调色。不要在页脚上方或页脚内部重复显示。
• 页脚应保持开放、简洁：不要有顶部边框、强调色条、重复的系统通知或带框列。
• 主操作使用填充式蓝绿色或近黑色控件。次要操作不要使用描边样式。
• 保留焦点指示器。键盘焦点轮廓是无障碍功能，不是装饰性边框。
• 使用项目的实际品牌标识资源。优先使用项目徽标；没有徽标时使用项目网站图标。

要移除的旧版样式

不要生成：

• 用于视觉分组的 border、border-*、divide-* 或卡片轮廓
• rounded、rounded-md、rounded-lg、药丸形卡片或圆角表格外框
• 重复的页眉和页脚公告栏
• 页脚 border-top、签名分隔线或青色／蓝绿色条纹
• 项目徽标或网站图标可用时使用通用 Lucide 象形图
• 带边框的次要按钮或提示框
• 框中套框的内容

原生文档分隔线、图表轴线、图表边缘、带下划线的文本链接和焦点轮廓不属于装饰性容器边框。只有在它们具有实际含义时才使用。

3. 品牌形象与语气

角色定位： 创新、技术专业，像一位资深解决方案架构师。

语气： 清晰、简洁、具体且权威。避免空洞的营销辞藻。

语言： 面向公众和商业场景的内容使用德语；技术文档使用英语，除非项目另有规定。

4. 视觉令牌

核心配色

令牌	浅色	深色	用途
--webcon-primary	#1b7a95	#66c4e1	主操作、链接、活动状态
--webcon-primary-dark	#155d73	#9dd8eb	悬停状态、醒目的蓝绿色文本
--webcon-primary-strong	#0f4555	#c5e8f2	深色品牌表面
--webcon-accent	#66c4e1	#66c4e1	页眉标识、非文本强调
--webcon-primary-pale	#e8f4f8	#0f3d4a	选中和信息类表面
--webcon-canvas	#f5f8f9	#071f26	应用背景
--webcon-surface	#ffffff	#0f252c	主要阅读表面
--webcon-surface-muted	#eef2f3	#16343d	导航和元数据区域
--webcon-ink	#171a1d	#f8fafb	主要文本
--webcon-muted	#5e6870	#b8c5ca	次要文本

浅青色是强调色，不应用作白色背景上的正文文本。将任何品牌色用于文本之前，都要检查对比度。

语义状态

状态	前景色	浅色表面	深色表面
成功	#166534	#dcfce7	#14532d
错误	#b42318	#fee2e2	#450a0a
警告	#9a4a00	#fef3c7	#451a03
信息	#155d73	#e8f4f8	#0f3d4a

通过填充表面、图标、标签和文本来表达状态。不要只用彩色边框作为唯一信号。

CSS 基础样式

:root {
  --webcon-primary: #1b7a95;
  --webcon-primary-dark: #155d73;
  --webcon-primary-strong: #0f4555;
  --webcon-accent: #66c4e1;
  --webcon-primary-pale: #e8f4f8;
  --webcon-canvas: #f5f8f9;
  --webcon-surface: #ffffff;
  --webcon-surface-muted: #eef2f3;
  --webcon-ink: #171a1d;
  --webcon-muted: #5e6870;
  --radius: 0;
}

*, *::before, *::after {
  border-radius: 0;
}

不要应用全局 border: 0；这可能会抹除有意义的控件、焦点指示器、图表坐标轴和第三方小组件。在组件级别移除装饰性边框。

5. 字体排印

在整个产品和公开网站中使用 Hanken Grotesk。

用途	字重	指引
正文	400	基础字号为 16px，行高为 1.5-1.65
展示文字和页面标题	500-650	字距紧凑，行高紧凑
UI 标签和次级标题	600-650	简短易扫读
主要操作和表格标题	650-700	仅用于强调
代码和标识符	400-700	JetBrains Mono 或系统等宽字体

import { Hanken_Grotesk } from 'next/font/google'

export const hankenGrotesk = Hanken_Grotesk({
  subsets: ['latin'],
  variable: '--font-hanken-grotesk',
  display: 'swap',
})

--font-sans: var(--font-hanken-grotesk), ui-sans-serif, system-ui, sans-serif;
--font-mono: "JetBrains Mono", ui-monospace, monospace;

公开页面的主视觉标题使用约 clamp(2.5rem, 5vw, 4.75rem) 的字号、500 的字重和略微紧缩的字距。内部工具应保持更紧凑。

6. 布局与间距

使用 4px 基础网格。

令牌	值	用途
space-1	4px	图标与文本紧凑对齐
space-2	8px	行内分组
space-3	12px	紧凑控件
space-4	16px	组件内边距
space-6	24px	相关内容块
space-8	32px	页面分组
space-12	48px	紧凑区块
space-16	64px	标准公开页面区块
space-24	96px	大区块节奏
space-32	128px	编辑内容与主视觉的间隔

• 公开页面：留白充足，采用全宽黑白或浅色表面变化，并确保内容宽度便于阅读。
• 内部工具：使用浅色画布、一个开放的白色工作表面，并保持克制的密度。
• 避免使用由相同边框卡片组成的网格。采用开放式分栏、横向区块和排版分组。
• 保持精确对齐。基线和边缘错位会让方形系统显得不协调。

7. 页眉与页脚

系统可以使用一条页眉公告或一条细窄的强调线。它必须只在体验顶部出现一次。

<header className="bg-white text-webcon-ink">
  <div aria-hidden="true" className="h-1 w-full bg-webcon-accent" />
  <nav className="mx-auto flex max-w-7xl items-center px-6 py-5">
    {/* logo, navigation, utilities */}
  </nav>
</header>

<main>{/* page */}</main>

<footer className="bg-webcon-ink px-6 py-16 text-white">
  {/* no top border, no accent rule, no repeated announcement */}
</footer>

对于 GitLab 等同时提供页眉和页脚通知的系统，只配置页眉通知，并将页脚通知留空。不要在每个页面的两端重复安全或平台相关文案。

8. 组件模式

按钮

<button class="bg-webcon-primary px-6 py-3 font-semibold text-white transition-colors hover:bg-webcon-primary-dark focus-visible:outline focus-visible:outline-3 focus-visible:outline-offset-2 focus-visible:outline-webcon-primary-dark">
  Primary action
</button>

<button class="bg-neutral-100 px-6 py-3 font-semibold text-webcon-ink transition-colors hover:bg-webcon-primary-pale focus-visible:outline focus-visible:outline-3 focus-visible:outline-offset-2 focus-visible:outline-webcon-primary-dark">
  Secondary action
</button>

<button class="bg-transparent px-4 py-2 font-semibold text-webcon-muted hover:bg-neutral-100 hover:text-webcon-primary-dark focus-visible:outline focus-visible:outline-3 focus-visible:outline-offset-2 focus-visible:outline-webcon-primary-dark">
  Ghost action
</button>

所有按钮均使用 border-0 rounded-none shadow-none。当主要操作需要从繁杂背景中凸显时，可以添加轻微阴影。

表单

• 将表单控件放在对比鲜明的填充表面上，而不是为它们画框。
• 浅色输入框使用 bg-neutral-100 border-0 rounded-none。
• 使用常驻标签；占位符不能替代标签。
• 使用至少有 3:1 对比度的 3px 焦点轮廓。
• 通过间距和标题对相关字段进行分组，不要用外围字段集边框。
• 保留原生复选框/单选框样式，或使用 accent-color: #1b7a95。

表格与列表

• 对账簿类表格使用填充的青绿色表头和白色文本。
• 使用白色和 #f8fafb 交替显示行；悬停和选中状态使用浅青绿色。
• 不要使用表格外边框、单元格网格或圆角表格容器。
• 数字右对齐，标识符使用等宽字体。
• 行操作保持紧凑，默认视觉上保持低调，仅在悬停或聚焦时突出显示。
• 移动端可选择横向滚动、优先级列视图或语义化列表。

卡片与面板

• 优先不使用卡片。让内容直接置于页面上或全宽表面区块中。
• 必须分组时，使用 bg-white 或 bg-webcon-primary-pale 并添加内边距。
• 不要通过添加边框或圆角来弥补层级不足。
• 静态内容不使用阴影。

标签页和导航

• 使用字体排版、填充式选中状态或简短的活动指示条。
• 不要为每个标签页绘制完整矩形边框。
• 保持页眉强调色与标签页选中状态有所区别；不要再添加贯穿整页的线条。

提示框、代码和叠加层

• 提示框：带色调的方形表面、清晰的图标、标题和文本；不要添加边框。
• 代码：近黑色方形表面、语法高亮颜色、文件名标签；不要添加装饰性边框。
• 菜单／对话框：方形表面，配以克制的阴影；不要保留卡片边框。

9. 项目标识与图标

项目图标必须代表项目本身，而不是界面选择的类别。

按以下顺序选择来源：

1. 项目仓库、品牌套件或已部署网站中的官方项目徽标。
2. 项目提供的产品／应用图标。
3. 已部署网站声明的最高质量 favicon（依次为 SVG、Web 清单、Apple touch icon，然后是 PNG／ICO）。
4. 仅当找不到徽标或 favicon 时，才使用中性的 webconsulting 备用图标。

规则：

• 如果有可用的徽标，不要用通用 Lucide 图标、表情符号、字母或类别象形图替代。
• 除非品牌指南允许，否则不要重绘、重新着色、裁剪第三方徽标，也不要在其后添加青绿色底块。
• 优先使用 SVG。否则使用最大的清晰栅格图，并保持其宽高比。
• 将项目头像规范为方形画布，并使用 object-fit: contain，保留 12-16% 的安全空间。
• 使用透明或低调的中性画布；不要添加边框或圆角遮罩。
• 保持徽标在视觉上居中。不要强行让文字标识填满方形区域。
• 记录来源 URL 或仓库路径，以便日后更新资源。
• 如果图标后面紧接着显示项目名称，使用空 alt 文本； 否则使用项目名称作为无障碍标签。

如果可行，必须通过页面元数据或 Web 清单解析 favicon。若项目网站能提供自己的资源，不要默认使用第三方 favicon 代理。

10. MDX 组件

如果存在项目 MDX 组件，请使用它们，而不是原始 HTML。

<Tabs defaultValue="v14">
  <TabsList>
    <TabsTrigger value="v14">TYPO3 v14</TabsTrigger>
  </TabsList>
  <TabsContent value="v14">Content for TYPO3 v14...</TabsContent>
</Tabs>

<ComparisonTable
  headers={['Feature', 'TYPO3 v14']}
  rows={[
    { label: 'Content Blocks 2.x', values: [true] },
    { label: 'Symfony 7.4', values: [true] },
  ]}
/>

<Callout type="info" title="Best Practice">
  Use a filled semantic surface without a border.
</Callout>

<MDXImage
  src="/images/architecture-diagram.png"
  alt="TYPO3 extension architecture"
  caption="Figure 1: Domain-driven TYPO3 architecture"
/>

即使上游组件自带边框或圆角，也要将这些组件实现为方形、无边框表面。

11. Mermaid 图表

保留语义图边，但移除装饰性的节点和簇描边。

%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#1b7a95',
  'primaryTextColor': '#ffffff',
  'primaryBorderColor': '#1b7a95',
  'lineColor': '#5e6870',
  'secondaryColor': '#e8f4f8',
  'tertiaryColor': '#f5f8f9',
  'clusterBorder': '#f5f8f9',
  'edgeLabelBackground': '#ffffff'
}}}%%
graph TD
    A[Client request] --> B[TYPO3]
    B --> C[Response]

对矩形节点和簇应用 rx: 0、ry: 0 和 stroke-width: 0。 不要移除箭头和关系线；它们承载信息。

12. 无障碍（WCAG 2.2 AA）

• 普通文本：对比度至少为 4.5:1。
• 大号文本和必要的 UI 图形：对比度至少为 3:1。
• 使用 :focus-visible，设置 3px 高对比度轮廓和 2px 偏移。
• 保持 DOM 结构和标签页顺序符合逻辑；切勿使用正数 tabindex。
• 在适当的位置为内容、导航和页脚提供跳转链接。
• 为每张信息性图片提供有意义的 alt 文本；装饰性图片使用 alt=""。
• 不要仅通过颜色传达状态。
• 触控目标至少为 24×24 CSS px；主要控件优先使用 44×44。
• 确保在 320 CSS px 下能够重排，且页面无需二维滚动。

13. 响应式行为

断点	宽度	Tailwind
移动端	< 640px	default
平板	>= 640px	sm:
桌面端	>= 1024px	lg:
宽屏	>= 1280px	xl:

应先减少列数，再缩小易读文字。保留表面层级，避免将每个移动端项目都变成带圆角边框的卡片。

14. 深色模式

深色模式应保留相同的方形、无边框层级。使用近黑色／海军蓝画布、稍浅的工作表面、用于交互强调的浅青色，以及浅色文本。不要通过添加浅色模式中不存在的边框来凸显结构。

15. shadcn/ui 集成

映射语义化令牌，然后移除默认卡片样式：

:root {
  --radius: 0rem;
  --background: 195 20% 97%;
  --foreground: 210 11% 10%;
  --primary: 193 69% 35%;
  --primary-foreground: 0 0% 100%;
  --muted: 195 17% 94%;
  --accent: 195 61% 94%;
  --ring: 193 69% 27%;
}

• 为卡片、按钮、字段、标签页和提示框添加 rounded-none border-0 shadow-none。
• 使用填充式表面和焦点轮廓重新构建字段边界。
• 保留 Radix 语义、键盘行为和焦点管理。
• 不要全局隐藏焦点环或原生禁用状态。

16. 审核清单

发布前，请确认：

• 除固有的圆形数据或图标几何形状外，所有圆角半径均为零。
• 静态容器不使用装饰性边框。
• 页眉通知／强调元素只出现一次；页脚不出现通知／强调元素。
• 页脚没有顶部横线，也不会重复页眉文案。
• 无需使用描边按钮，主操作也能在视觉上清晰突出。
• 仅通过表面、间距和字体即可保持层级清晰。
• 项目图标使用真实徽标或网站图标回退方案，并记录来源。
• 移除边框后，焦点仍清晰可见。
• 浅色／深色对比度和 320px 下的重排均通过检查。

来源：https://github.com/dirnbauer/webconsulting-skills