Skip to content

Commit e104f47

Browse files
wchwch
committed
Add brand.yml prompt
1 parent 1332001 commit e104f47

File tree

4 files changed

+250
-0
lines changed

4 files changed

+250
-0
lines changed

‎assistant-prompts/brand_yml.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
## About brand.yml
2+
3+
brand.yml is a structured YAML file to hold brand information for key
4+
brand elements. The goal of brand.yml is to capture the essence of the
5+
brand's color and typographic choices in a simple format.
6+
7+
"brand.yml" is the name of the project defining the YAML specification.
8+
A specific instance of a brand's data is stored in a file named
9+
"_brand.yml" by convention.
10+
11+
## Brand Elements
12+
13+
- `meta` - Key identity information, name of the company, links to
14+
brand guidelines, etc.
15+
16+
- `logo` - Files or links to the brand's logo at various sizes.
17+
18+
- `color` Semantic colors, e.g. `primary`, `secondary`, `success`,
19+
`warning`, etc. Named colors in the brand's color palette are stored
20+
in `color.palette`.
21+
22+
- `typography` - Font family, weight, style, color, and line height
23+
for key elements, e.g. base, headings and monospace text. Available
24+
fonts used by the brand are stored in `typography.fonts` and can be
25+
sourced from Google Fonts, Bunny Fonts or local or remote font
26+
files.
27+
28+
- `defaults` - Additional context-specific settings beyond the basic
29+
brand colors and typography. These could be options, for example,
30+
that are used by Bootstrap in Quarto or Shiny. They could also be
31+
folded into existing Quarto yaml fields like `format` or `website`,
32+
or they could be new fields for other contexts like `shiny`.
33+
34+
## Example file
35+
36+
The following YAML includes all allowed features of a _brand.yml file.
37+
Note that all fields are optional.
38+
39+
Only include fields that directly apply to the brand; it's important for
40+
the _brand.yml file to be simple and concise rather than overly
41+
complex. Many fields have simple and complex values variants; generally
42+
speaking many fields accept either a simple string or a mapping.
43+
Alternative syntax is indicated in comments in the example below with
44+
"ALT". If possible, use the simple string.
45+
46+
``` {.yaml filename="_brand.yml"}
47+
meta:
48+
# name: Acme # ALT: Single string for simple company name
49+
name:
50+
short: Acme # Short company name
51+
full: Acme Corporation International # Full, legal company name
52+
53+
# link: https://acmecorp.com # ALT: single url for the company's home page
54+
link:
55+
home: https://www.acmecorp.com # Company's home apge
56+
bluesky: https://bsky.app/profile/acmecorp.bsky.social # Bluesky social media account link
57+
github: https://github.com/acmecorp # GitHub account link
58+
mastodon: https://mastodon.social/@acmecorp # Mastodon account link
59+
linkedin: https://www.linkedin.com/company/acmecorp # LinkedIn account link
60+
facebook: https://www.facebook.com/acmecorp # Facebook account link
61+
twitter: https://twitter.com/acmecorp # Twitter account link
62+
63+
logo:
64+
images: # Mapping of image names to local files that should be stored next to the _brand.yml file. Users may need to download these files manually.
65+
header: logos/header-logo.png # Each entry maps a name to a local file
66+
header-white: logos/header-logo-white.png
67+
full: # ALT: Images can alternatively be a path with associated alt text for accessibility
68+
path: logos/full-logo.svg
69+
alt: Acme logo.
70+
small: logos/icon.png # A small image, ideally icon-sized. Can be a path to a file or the name of a file in `logo.images`
71+
medium: # A medium sized logo, ideally small enough for a sidebar logo
72+
# ALT: Logos is small, medium, and large may have `light` and `dark` variants
73+
light: header # light variant for use on light backgrounds
74+
dark: header-white # dark variant for use on dark backgrounds
75+
large: full # A large logo, e.g. for use in a hero or cover page. ALT: Can refer directly to images in `logo.images`.
76+
77+
color:
78+
palette:
79+
# Dictionary of the brand's colors with readable names.
80+
# Must be a flat list of names and color values.
81+
# Names should be follow Sass variable conventions. Prefer hex color values.
82+
# Prefer or create aliases for Bootstrap primary colors: blue, indigo, purple, pink, red, orange, yellow, green, teal, cyan, white, black
83+
white: "#FFFFFF"
84+
black: "#151515"
85+
blue: "#447099"
86+
orange: "#EE6331"
87+
green: "#72994E"
88+
teal: "#419599"
89+
burgundy: "#9A4665"
90+
purple: burgundy # Aliases are allowed by referring to other colors in `color.palette`
91+
fire-red: "#FF0000"
92+
bright-yellow: "#FFFF00"
93+
94+
# All theme colors can take direct color values, and all are optional.
95+
# Only include the colors that are obviously required.
96+
# Refer to color names from `color.palette` whenever possible.
97+
foreground: "#151515" # Main text color, should have high contrast with background
98+
background: "#FFFFFF" # Main background color, should have high contrast with foreground
99+
primary: "#447099" # Main accent color for links, buttons, etc.
100+
secondary: "#707073" # Used for lighter text or disabled states. Only include if necessary.
101+
tertiary: "#C2C2C4" # Even lighter color for hover states, accents, wells. Only include if necessary.
102+
success: "#72994E" # Color for positive or successful actions/information
103+
info: "#419599" # Color for neutral or informational actions/information
104+
warning: "#EE6331" # Color for warning or cautionary actions/information,
105+
danger: "#9A4665" # Color for errors, dangerous actions, negative information
106+
light: "#FFFFFF" # Bright color for high-contrast on dark elements
107+
dark: "#404041" # Dark color for high-contrast on light elements
108+
# ALT: All properties in `color` can refer by name to values in `color.palette`, including within `color.palette`.
109+
# foreground: black
110+
# background: white
111+
# primary: blue
112+
# success: green
113+
# info: teal
114+
# ALT: All properties in `color` can refer by name to other properties in `color`.
115+
116+
typography:
117+
fonts:
118+
- family: Open Sans # Font family name
119+
source: file # Source of the font (file, google, bunny, or system)
120+
files: # REQUIRED list of font files for `source: file`, which must have at least one font file. Use placeholder names and comment out the source font section if proprietary fonts are used. (And include a Google Font alternative recommendation.)
121+
- path: fonts/open-sans/OpenSans-Variable.ttf
122+
# Each file corresponds to a weight and style, both default to "normal".
123+
weight: 400 # Optional: specify weight for this file
124+
style: normal # Optional: specify style for this file
125+
- path: fonts/open-sans/OpenSans-Variable-Italic.ttf
126+
style: italic
127+
- family: Roboto Slab
128+
source: google
129+
weight: [600, 900] # Optional font weights to include (for google and bunny), defaults to all weights
130+
# weight: 600..900 # ALT: fonts with variable weights can have a weight range
131+
# weight: [thin, normal, bold] # ALT: font weights by name are allowed
132+
style: [normal, italic] # Font styles to include (for google and bunny)
133+
display: block # Font display property (for google). Optional and should not be included in most cases.
134+
- family: Fira Code
135+
source: bunny # Use Bunny Fonts, a GDPR-compliant alternative to Google Fonts
136+
weight: [400, 500, 600] # Optional, same as for `source: google`
137+
style: [normal, italic] # Optional, same as for `source: google`
138+
139+
# base: Open San # ALT: If a string, sets the base font family
140+
base:
141+
family: Open Sans # Optional: Font family for body text
142+
weight: 400 # Optional: Font weight for body text
143+
size: 16px # Optional: Font size for body text, allows any CSS value, rem or px are preferred
144+
line-height: 1.5 # Optional: Line height for body text
145+
# DO NOT INCLUDE color HERE. The base font uses `color.foreground` by default.
146+
147+
# headings: Roboto Slab # ALT: If a string, sets the headings font family
148+
headings:
149+
family: Roboto Slab # Optional: Font family for headings
150+
weight: 600 # Optional: Font weight for headings
151+
style: normal # Optional: Font style for headings
152+
line-height: 1.2 # Optional: Line height for headings
153+
color: "#333333" # Optional: Color for headings
154+
# color: primary # ALT: Can use named colors from `color` or `color.palette`
155+
156+
# monospace: Fira Code # ALT: If a string, sets the monospace font family
157+
monospace:
158+
family: Fira Code # Optional: Font family for monospace text
159+
weight: 400 # Optional: Font weight for monospace text
160+
size: 0.9em # Optional: Font size for monospace text, CSS units allowed but `rem` or `px` preferred
161+
monospace-inline: # Inline monospace text, inherits from monospace
162+
# Properties of monospace can be overwritten here
163+
color: "#7d12ba" # Color for inline monospace text, ALT: named colors from `color` or `color.palette`
164+
background-color: "#f8f9fa" # Background color for inline monospace text, ALT: named colors from `color` or `color.palette`
165+
monospace-block:
166+
color: foreground # Color for block monospace text, ALT: named colors from `color` or `color.palette`
167+
background-color: background # Background color for block monospace text, ALT: named colors from `color` or `color.palette`
168+
line-height: 1.4 # Line height for block monospace text
169+
link:
170+
weight: 600 # Font weight for links
171+
color: "#0066cc" # Optional color for link, defaults `color.primary`. ALT: named colors from `color` or `color.palette`
172+
background-color: transparent # Optional background color for links, ALT: named colors from `color` or `color.palette`
173+
decoration: underline # Optional text decoration for links
174+
175+
defaults: # Additional Bootstrap, Shiny, or Quarto rules, all optional and only to be used as a last resort
176+
bootstrap: Additional scss rules for any contexts that use Bootstrap
177+
functions: # string with scss function declarations
178+
defaults: # Mapping of Bootstrap variables to default values
179+
mixins: # string with scss mixins
180+
rules: # string with scss rules
181+
quarto:
182+
format:
183+
# Options specific to output Quarto output formats
184+
shiny:
185+
theme: # Additional scss rules to add to the Shiny branded theme
186+
defaults:
187+
# Named bootstrap variables and their default values
188+
navbar-bg: $brand-orange # Use Sass variables to access brand colors: $brand-{color_name}
189+
rules:
190+
# A string of additional scss rules
191+
```
192+
193+
## Brand best practices
194+
195+
Be careful and be certain to follow these rules when creating the
196+
`_brand.yml` file:
197+
198+
- When brands define a range of shades and tints for colors, it's best
199+
to choose the midpoint color as the primary color used in the
200+
`color.palette`.
201+
202+
- For logo and font files, use placeholders in the `_brand.yml` with
203+
instructions to download the files and place them next to
204+
`_brand.yml`.
205+
206+
- Suggest substitutes for proprietary fonts by finding the closest
207+
equivalent fonts on Google Fonts.
208+
209+
- Prefer hex color syntax for raw color values.
210+
211+
## Using `_brand.yml` in Shiny applications
212+
213+
{{ @if (it.language === "R") }}
214+
{{ @includeFile("brand_yml_r.md", it)/}}
215+
{{ #elif (it.language === "Python") }}
216+
{{ @includeFile("brand_yml_python.md", it)/}}
217+
{{ /if}}`

‎assistant-prompts/brand_yml_python.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
To use a _brand.yml file in Shiny for Python, this is how to do it with Shiny Express syntax:
2+
3+
```py
4+
from shiny.express import input, render, ui
5+
6+
ui.page_opts(theme=ui.Theme.from_brand(__file__))
7+
```
8+
9+
And this is how to do it with Shiny Core Syntax:
10+
11+
```py
12+
from shiny import ui
13+
14+
app_ui = ui.page_fluid(
15+
# App UI code...
16+
theme=ui.Theme.from_brand(__file__)
17+
)
18+
```
19+
20+
It also requires installing the `brand_yml` and `libsass` packages, so it should be added to `requirements.txt`.
21+

‎assistant-prompts/brand_yml_r.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
To use a _brand.yml file in Shiny for R, pass it as the `theme` argument to a `page_*` function.
2+
3+
```R
4+
ui <- page_sidebar(
5+
title = "Acme Sales Dashboard",
6+
theme = bs_theme(brand = "acme-brand.yml"),
7+
# ... the rest of your app ...
8+
)
9+
```

‎assistant-prompts/main.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,9 @@ Here is another example:
131131
{{ /if}}`
132132

133133

134+
{{ @includeFile("brand_yml.md", it)/}}
135+
136+
134137
Consider multiple possible implementations of the application, then choose the best one. Remember to create a fully functional Shiny for {{it.language}} app that accurately reflects the user's requirements. If you're unsure about any aspect of the app, make a reasonable decision and explain your choice in a comment.
135138

136139
{{it.verbosity}}

0 commit comments

Comments
 (0)