From b38a584d6b1651f799ddfd97d7733d7e5bca756b Mon Sep 17 00:00:00 2001 From: Mike Mai Date: Mon, 27 Sep 2021 12:02:31 -0400 Subject: [PATCH 1/3] docs: nuke obsolete docs --- .../pages/docs/00-getting-started/00-index.md | 99 ---- docs-site/src/pages/docs/00-index.md | 3 - .../docs/25-design-principles/00-index.md | 22 - .../25-design-principles/05-accessibility.md | 44 -- .../25-design-principles/10-interface-copy.md | 72 --- .../src/pages/docs/45-development/00-index.md | 5 - .../00-index.md | 5 - .../10-architecture-principles.md | 277 ---------- .../10-javascript.md | 54 -- .../01-local-dev-environment-setup.md | 143 ----- .../10-server-side-rendering.md | 84 --- .../pages/docs/45-development/20-sassdocs.md | 5 - .../45-development/25-patching=npm-package.md | 32 -- .../45-development/30-build-tools/00-index.md | 5 - .../30-build-tools/01-boltrc-config.md | 13 - .../30-build-tools/10-basic-config.md | 22 - .../30-build-tools/20-components.md | 25 - .../45-development/30-build-tools/30-envs.md | 16 - .../30-build-tools/40-internationalization.md | 53 -- .../30-build-tools/_40-extras.md | 73 --- .../50-developer-tools/00-index.md | 5 - .../10-using-xdebug-for-PHP.md | 216 -------- .../70-testing-standards/00-index.md | 5 - .../10-js-testing-standards.md | 507 ------------------ .../20-manual-testing-standards.md | 56 -- .../docs/45-workflow-and-process/00-index.md | 5 - .../10-release-types.md | 60 --- .../20-cutting-a-release.md | 152 ------ .../src/pages/docs/50-guides/00-index.md | 6 - .../docs/50-guides/10-browser-support.md | 64 --- .../docs/50-guides/10-install-component.md | 26 - .../50-guides/15-building-a-new-component.md | 35 -- .../docs/50-guides/20-troubleshooting.md | 15 - .../docs/50-guides/30-adding-custom-icons.md | 25 - .../docs/50-guides/40-road-runner-rules.md | 73 --- .../50-tips-on-building-web-components.md | 42 -- .../docs/50-guides/60-migrating-to-3.x.md | 35 -- docs-site/src/pages/docs/_00-faq.md | 99 ---- docs-site/src/pages/docs/_00-resources.md | 104 ---- .../pages/docs/_15-whats-new-in-bolt-v1.md | 111 ---- docs-site/src/pages/docs/_20-releases.md | 5 - .../pages/docs/_30-ui-patterns/00-index.md | 6 - .../src/pages/docs/_30-ui-patterns/bands.md | 141 ----- .../pages/docs/_30-ui-patterns/blockquotes.md | 37 -- .../src/pages/docs/_30-ui-patterns/buttons.md | 55 -- .../src/pages/docs/_30-ui-patterns/cards.md | 45 -- .../src/pages/docs/_30-ui-patterns/forms.md | 109 ---- .../docs/_40-visual-language/00-index.md | 5 - .../docs/_40-visual-language/10-colors.md | 49 -- .../docs/_40-visual-language/20-typography.md | 87 --- .../_40-visual-language/30-iconography.md | 62 --- .../docs/_40-visual-language/40-spacing.md | 55 -- 52 files changed, 3349 deletions(-) delete mode 100644 docs-site/src/pages/docs/00-getting-started/00-index.md delete mode 100644 docs-site/src/pages/docs/00-index.md delete mode 100644 docs-site/src/pages/docs/25-design-principles/00-index.md delete mode 100644 docs-site/src/pages/docs/25-design-principles/05-accessibility.md delete mode 100644 docs-site/src/pages/docs/25-design-principles/10-interface-copy.md delete mode 100644 docs-site/src/pages/docs/45-development/00-index.md delete mode 100644 docs-site/src/pages/docs/45-development/00-standards-and-best-practices/00-index.md delete mode 100644 docs-site/src/pages/docs/45-development/00-standards-and-best-practices/10-architecture-principles.md delete mode 100644 docs-site/src/pages/docs/45-development/00-standards-and-best-practices/10-javascript.md delete mode 100644 docs-site/src/pages/docs/45-development/01-local-dev-environment-setup.md delete mode 100644 docs-site/src/pages/docs/45-development/10-server-side-rendering.md delete mode 100644 docs-site/src/pages/docs/45-development/20-sassdocs.md delete mode 100644 docs-site/src/pages/docs/45-development/25-patching=npm-package.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/00-index.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/01-boltrc-config.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/10-basic-config.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/20-components.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/30-envs.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/40-internationalization.md delete mode 100644 docs-site/src/pages/docs/45-development/30-build-tools/_40-extras.md delete mode 100644 docs-site/src/pages/docs/45-development/50-developer-tools/00-index.md delete mode 100644 docs-site/src/pages/docs/45-development/50-developer-tools/10-using-xdebug-for-PHP.md delete mode 100644 docs-site/src/pages/docs/45-development/70-testing-standards/00-index.md delete mode 100644 docs-site/src/pages/docs/45-development/70-testing-standards/10-js-testing-standards.md delete mode 100644 docs-site/src/pages/docs/45-development/70-testing-standards/20-manual-testing-standards.md delete mode 100644 docs-site/src/pages/docs/45-workflow-and-process/00-index.md delete mode 100644 docs-site/src/pages/docs/45-workflow-and-process/10-release-types.md delete mode 100644 docs-site/src/pages/docs/45-workflow-and-process/20-cutting-a-release.md delete mode 100644 docs-site/src/pages/docs/50-guides/00-index.md delete mode 100644 docs-site/src/pages/docs/50-guides/10-browser-support.md delete mode 100644 docs-site/src/pages/docs/50-guides/10-install-component.md delete mode 100644 docs-site/src/pages/docs/50-guides/15-building-a-new-component.md delete mode 100644 docs-site/src/pages/docs/50-guides/20-troubleshooting.md delete mode 100644 docs-site/src/pages/docs/50-guides/30-adding-custom-icons.md delete mode 100644 docs-site/src/pages/docs/50-guides/40-road-runner-rules.md delete mode 100644 docs-site/src/pages/docs/50-guides/50-tips-on-building-web-components.md delete mode 100644 docs-site/src/pages/docs/50-guides/60-migrating-to-3.x.md delete mode 100644 docs-site/src/pages/docs/_00-faq.md delete mode 100644 docs-site/src/pages/docs/_00-resources.md delete mode 100644 docs-site/src/pages/docs/_15-whats-new-in-bolt-v1.md delete mode 100644 docs-site/src/pages/docs/_20-releases.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/00-index.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/bands.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/blockquotes.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/buttons.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/cards.md delete mode 100644 docs-site/src/pages/docs/_30-ui-patterns/forms.md delete mode 100644 docs-site/src/pages/docs/_40-visual-language/00-index.md delete mode 100644 docs-site/src/pages/docs/_40-visual-language/10-colors.md delete mode 100644 docs-site/src/pages/docs/_40-visual-language/20-typography.md delete mode 100644 docs-site/src/pages/docs/_40-visual-language/30-iconography.md delete mode 100644 docs-site/src/pages/docs/_40-visual-language/40-spacing.md diff --git a/docs-site/src/pages/docs/00-getting-started/00-index.md b/docs-site/src/pages/docs/00-getting-started/00-index.md deleted file mode 100644 index 7d5b127a11..0000000000 --- a/docs-site/src/pages/docs/00-getting-started/00-index.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Getting Started -category: Quick Start ---- - -## Create bolt config file - -Create a file called `.boltrc.js` with: - - -module.exports = { - buildDir: 'www/build', - components: { - global: [ - ], - individual: [ - ], - }, -}; - - -## Install Build Tools - -Ensure you have a `package.json` file, if not, run `npm init`. - -```bash -npm install --save @bolt/build-tools -``` - -Add this to your `package.json`: - -```diff -"scripts": { -+ "build": "bolt build", -+ "build:prod": "NODE_ENV=production bolt build", -+ "start": "bolt start" -} -``` - -## Consider adding global styling - -All global styles are kept in a single package, if you'd like it, run: - -```bash -npm install --save @bolt/global -``` - -Then add it to `.boltrc.js`: - -```diff -module.exports = { - buildDir: 'www/build', - components: { - global: [ -+ '@bolt/global', - ], - individual: [ - ], - }, -}; -``` - -## Install Components - -Install any Bolt Component via `npm` as it's docs suggest. If you were going to install the Button, you'd run: - -```bash -npm install --save @bolt/components-button -``` - -Then add it to `.boltrc.js`: - -```diff -module.exports = { - buildDir: 'www/build', - components: { - global: [ - '@bolt/global', -+ '@bolt/components-button', - ], - individual: [ - ], - }, -}; -``` - -Continue to do so with as many components as you'd like. - -## Build It - -Run this to build: - -```bash -npm run build -``` - -You can optionally run `npm run build:prod` for smaller files sizes - though it does take longer. CI should run this command. - -All files will build to the directory you've configured as your `buildDir`. diff --git a/docs-site/src/pages/docs/00-index.md b/docs-site/src/pages/docs/00-index.md deleted file mode 100644 index f15cbd3745..0000000000 --- a/docs-site/src/pages/docs/00-index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Getting Started ---- diff --git a/docs-site/src/pages/docs/25-design-principles/00-index.md b/docs-site/src/pages/docs/25-design-principles/00-index.md deleted file mode 100644 index 253f74c5b5..0000000000 --- a/docs-site/src/pages/docs/25-design-principles/00-index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -category: Design Principles -title: Overview ---- - -The Digital team at Pegasystems creates, maintains and continuously improves the websites that help people learn, build with, sell and buy Pega applications. The 5+ digital properties we work on span internal and external audiences across offices in North America, Europe, and the Asia Pacific region. The following principles help us deliver effective, thoughtful design for the Bolt Design System. - -## Clarity > Cleverness. - -When information isn't clear, it doesn't matter how clever it is. Use plain language and avoid jargon, especially in helper text. Use animation cautiously - it should assist user interaction, rather than obfuscating it. - -## Accessibility is not optional. - -Thinking about accessibility is more than just caring about screen readers. Designing for accessibility helps people with low vision, color blindness and other minor visual issues best interact with our work. [It also helps with SEO](https://webaim.org/blog/web-accessibility-and-seo/). - -## Consider the ecosystem. - -Everything we create fits into a broader digital ecosystem. Understand where the pieces we are working on fit within that ecosystem, and how we can reuse elements to create visual and UI consistency. - -## Make it shine. - -Usability isn't just about functionality or interaction design. If pages load slowly, or the experience lacks visual polish, the user experience suffers. Everything we create should take care to represent Pega in the best possible light. \ No newline at end of file diff --git a/docs-site/src/pages/docs/25-design-principles/05-accessibility.md b/docs-site/src/pages/docs/25-design-principles/05-accessibility.md deleted file mode 100644 index 7ef00ef918..0000000000 --- a/docs-site/src/pages/docs/25-design-principles/05-accessibility.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Accessibility ---- - -As the creator of products that sell into diverse industries, including government, the need for inclusive and accessible experiences is paramount. Paying attention to [universal design](https://en.wikipedia.org/wiki/Universal_design) principles in our design process sends an important message to our potential customers and partners that we comply with regulations. - -To put this issue in perspective, statistics show: - -- 9.1% of adults have some kind of vision trouble [Source: [Disability and Functioning, CDC](http://www.cdc.gov/nchs/fastats/disability.htm)] -- 8% of men and 0.5% of women are color blind [Source: [Color Blind Awareness](http://www.colourblindawareness.org/colour-blindness/)] -- 16.8% of adults have hearing trouble [Source: [Disability and Functioning, CDC](http://www.cdc.gov/nchs/fastats/disability.htm)] -- 15.1% of adults live with physical functioning difficulty [Source: [Disability and Functioning, CDC](http://www.cdc.gov/nchs/fastats/disability.htm)] -- 4.4% of adults have cognitive disabilities [Source: [2016 Disability Statistics Annual Report (PDF)](https://disabilitycompendium.org/sites/default/files/user-uploads/2016_AnnualReport.pdf)] - -## Built-in Inclusivity - -Using Bolt's re-usable components to improve accessibility and consistency when building Pega Digital Experiences. - -- Accessible markup is already included in the code. -- Since the code exists in a single component that gets reused, it’s easier to update and fix bugs - -## Color contrast | WCAG AA standards - -All type/color combinations in Bolt must pass [**WCAG AA standards**](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1 for normal text and 3:1 for large text. For larger text, if the font weight is light (300) or normal (400) the text should be no smaller than 24px. If the font weight is Semi-Bold (600) then the large text should be no smaller than 19px. - -### Do - -Minimal contrast ratio: 4.5 - -| ![1.0 White on Indigo](/images/docs/color_YES_white-on-indigo.png) | ![1.1 Indigo on Yellow](/images/docs/color_YES-indigo-on-yellow.png) | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| *1.0 White on Indigo* | *1.1 Indigo on Yellow* | -| ![1.2 Indigo on Gray](/images/docs/color_YES-indigo-on-gray.png) | ![1.3 Dark on White](/images/docs/color_YES_dark-on-white.png) | -| *1.2 Indigo on Gray* | *1.3 Dark on White* | - -## Don’t - -WCAG Fail - -| ![2.0 White on Teal](/images/docs/color_NO_white-on-teal.png) | ![2.1 White on Yellow](/images/docs/color_NO_white-on-yellow.png) | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| *2.0 White on Teal* | *2.1 White on Yellow* | -| ![2.2 Dark on Gray](/images/docs/color_NO_dark-on-gray.png) | ![2.3 White on Dark](/images/docs/color_NO_white-on-dark.png) | -| *2.2 Dark on Gray* | *2.3 White on Dark* | \ No newline at end of file diff --git a/docs-site/src/pages/docs/25-design-principles/10-interface-copy.md b/docs-site/src/pages/docs/25-design-principles/10-interface-copy.md deleted file mode 100644 index bdaf6ec8da..0000000000 --- a/docs-site/src/pages/docs/25-design-principles/10-interface-copy.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Interface Copy ---- - -As makers of compelling digital experiences, we know that content—particularly written content—is a key factor in how we express our brand. Paying attention to the voice and tone of our writing helps us reflect the Pega brand while maintaining awareness of each situation’s unique needs. - -## Voice and Tone - -Think about voice and tone as two sides of a similar coin. *Voice* is the brand’s overall personality: how we say things, the words we choose, and how we put sentences together. *Tone* is how that voice is reflected in a given situational or emotional context. For example, even if your *voice* is usually passionate and direct, you wouldn’t use the same *tone* to discuss your favorite movie as you would to address a work conflict. - -### Voice - -Pega’s brand personality is built on three characteristics: Passion, Power and Partnership. Across our Digital channels, our voice is: - -- **Clear and succinct**. Avoid technical jargon or Pega-specific abbreviations. -- **Authoritative**. Establish expertise up front without being arrogant. -- **Helpful**. Aim to educate and give people a clear path forward. -- **Direct.** Use short, declarative sentences, and remove unnecessary words. -- **Accessible**. Make sure that your writing can be understood by people whose primary language is not English. - -Our goal is to empower the people using our Digital experiences to make smart decisions and solve their problem—whether it’s understanding which Pega product meets their use case, or troubleshooting an implementation challenge. - -### Tone -While our voice stays consistent across channels, our tone changes depending on the user’s situational and emotional context. Some examples: - -- **System Errors**: Focus on a helpful, informative tone that tells the user what just happened, and how to fix the issue, e.g. “We couldn’t find that email/password combination. Please try again.” -- **Promotional copy**: Use a concise, confident tone that conveys expertise, e.g. "Want to put your competitors out of commission? Never give them a chance to steal your customers.“ -- **Technical content:** Focus on clearly walking someone through the major concepts, with screenshots as applicable, e.g. “Using Pega Co-Browse, a remote viewer can connect to a presenter’s browser instantly and show them sections of the website by highlighting different elements on the page.” - -## Style guidelines - -Below are some highlights from our style guide to use when writing copy for Digital interfaces. For an exhaustive list of style guidelines, Pega employees can download the *Pega Writing Style Guide* on Pega Brand Hub. - -### Abbreviations and acronyms - -For the clearest and most powerful writing, use abbreviations and acronyms as minimally as possible. If you are only mentioning a term once, do not abbreviate it – just spell it out. If you are mentioning a term more than once, write it out in full the first time you use it in a piece of content, then place the abbreviation in parentheses () immediately afterward. You can then use the abbreviation by itself for subsequent mentions. -**Example**: *Today, artificial intelligence (AI) is more than a buzzword. AI is a reality.* - -- No need to spell out common, non-technical terms like CEO, RSVP, etc. -- If an abbreviation uses all capital letters, don’t use periods in between the letters. - -### Active vs. passive voice - -Write in the active voice, not the passive voice – it’s more concise, more direct, and easier to understand (and translate). - -- **Passive:** *It was believed that a shift should be made to digital channels.* -- **Active:** *Bankers believed they should shift to digital channels.* -- **Passive:** *Customer service is improved by doing this.* -- **Active:** *This improves customer service.* - -### All caps, bold, italics, underline - -Reserve these for the few key words that you really want to emphasize. If overused, they can have the opposite effect – the reader won’t know what’s important and your message will lose impact. - -- Don’t combine them, like this, or use more than ONE type of emphasis per sentence. -- Bold or italics are preferable, especially when writing for digital. All caps signifies “shouting” and underlines are easily mistaken for hyperlinks. -- Don’t write full sentences in all caps, or use all caps near an abbreviation. - - **Incorrect**: *REAL CRM solutions work FASTER.* - - **Correct**: *Real CRM solutions work faster.* - -### Ampersands (“&”) - -Use an ampersand when it’s part of a brand name (*Procter & Gamble*) or occasionally to save space in a headline or email subject line: *Learn about AI & robotics*. Do not use ampersands in regular text. Avoid using both an ampersand and the word “and” in the same headline or group of headlines. - -### Global audiences - -Pega is a global company and much of our writing will either be translated into other languages or shared in markets where most people are not native English speakers. Keep these tips in mind when writing content that may be translated or shared internationally: - -- Avoid slang and local or national references. -- Don’t rely on puns or wordplay. Often these are lost in translation. -- Instead of long, complex sentences and flowery language, use short, clear sentences and precise wording. - diff --git a/docs-site/src/pages/docs/45-development/00-index.md b/docs-site/src/pages/docs/45-development/00-index.md deleted file mode 100644 index 9d0ea703f3..0000000000 --- a/docs-site/src/pages/docs/45-development/00-index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Development -category: Development -hidden: true ---- \ No newline at end of file diff --git a/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/00-index.md b/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/00-index.md deleted file mode 100644 index caed22534d..0000000000 --- a/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/00-index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Standards & Best Practices -category: Standards & Best Practices -hidden: true ---- diff --git a/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/10-architecture-principles.md b/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/10-architecture-principles.md deleted file mode 100644 index 13a582f43e..0000000000 --- a/docs-site/src/pages/docs/45-development/00-standards-and-best-practices/10-architecture-principles.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: Architecture Principles ---- - -# Bolt Frontend Architecture Principles - -**Part 1. Component Reuse and Composition** -1. Frequently used components should be the easiest ones to reuse and extend. -2. JavaScript components (and any underlying functionality) should be sharable and extendable. -3. Solve problems ~once~. Components rarely have to solve problems that other components / UI patterns don’t also have to solve. - -**Part 2. Component Consistency, Maintainability, & Emerging Standards** -1. Components should be authored consistently. -2. Emerging patterns should be discussed and shared. -3. Components should visually render and —whenever possible— include basic functionality and interactivity when JavaScript is disabled. -4. Components should support being used via a Twig include (which pulls in the web component’s custom element) or via the web component’s custom element directly. -5. Components should be encapsulated. If a totally separate component gets an API change, your component shouldn’t care. -6. Component composition > component inheritance. -7. Don’t repeat yourself. -8. Use the web component rendering engine best suited for a component’s needs (Preact vs Lit-HTML) - -**Part 3. People-friendly API + Reasonable Defaults** -1. Components should work with the smallest number of config options — ideally none if possible! -2. Use appropriate default prop values for different situations. -3. Batch together “either/or” props that shouldn’t be mixed and matched. -4. Component props that aren’t unique should be broken down and shared. -5. Use consistent, easy to remember prop names. -6. Rarely used component props < utility classes which do the exact same thing. - -**Part 4. Design System Feedback Loop** -1. Capture and discuss reoccurring pain-points. -2. Identify gaps in the Design System. -3. Refactor, Release, or Merge and Iterate? - - ---- - -## Part 1. Component Reuse and Composition - -### Frequently used components should be the easiest ones to reuse and extend. - -* Is it reasonable to assume that this a lower-level “core” component that’ll get frequently composed with (or functionality extended by) other higher level components in the design system? -* Or does this component primarily live on it’s own (limited composition expected) and/or doesn’t include underlying functionality or behavior that would reasonably need to get reused or extended by other components? - -The more frequent a component is expected to be reused (as a whole + reusing and sharing the underlying pieces / functionality that make up that component), the greater the importance of making a component can get easily reused and extended! - - -### JavaScript components (and any underlying functionality) should be sharable and extendable. - -Where does the majority of a component’s logic live? In the render method? In external helper functions? In exported functions that other components could pull in? - -- Can the component’s logic and behavior be easily extended / shared via one of the following methods? - - A. Extending the component’s base Class (logic primarily exists as standalone methods that are NOT baked into the render method) - - B. Importing component-specific functions that are exported as standalone JS standalone functions (functionality worth sharing isn’t directly baked into the component) - - C. Importing helper functions used by the component (but aren’t exclusive to the component itself) - - -### Solve problems ~once~. Components rarely have to solve problems that other components / UI patterns don’t also have to solve. - -- Does this component have logic that ONLY applies to this one component or is there any core functionality, behavior, or logic that applies more broadly to a range of components in the design system (especially components that already exist)? - ---- - -## Part 2. Component Consistency, Maintainability, & Emerging Standards - -### Components should be authored consistently. -- Does this component feel right at home with other recently authored components? -- Are the approaches, coding style, libraries, architectural patterns, etc in line with work that has been done elsewhere in the design system? - -### Emerging patterns should be discussed and shared. -- Or does anything (new technique, different / alternative approach, unexplored territory, experimental work, etc) stand out? -- If so, those things should get spelled out, documented and demoed with the team — not to get buy-in mind you, but to educate on how the system is evolving and growing! - -### Components should visually render and —whenever possible— include basic functionality and interactivity when JavaScript is disabled. -- The more essential and highly visible a component is, the more important the component looks —and when appropriate, behaves— when JavaScript is disabled, takes a long time to load or is unexpectedly broken. - -### Components should support being used via a Twig include (which pulls in the web component’s custom element) or via the web component’s custom element directly. -- Components being pre-rendered in Twig should automatically hydrate using the initial data passed along by the server and take over once the JavaScript kicks in. - -### Components should be encapsulated. If a totally separate component gets an API change, your component shouldn’t care. -- Is this component tied at the hip to one or more (“related but technically standalone”) nested components / “behaviors” in the design system OR does this component “just work” if any nested components have their APIs updated? - -> As a gut check, let’s say we added a new “isFancy” boolean prop to one of the component’s “related but technically separate” components, say, an icon. Do we need to update this component’s API every time the API of a nested component (the icon in this case) changes? If so, this means our two components are - -Examples we should be looking out for include icons, links, text and buttons — all of which are commonly used together but are nonetheless separate standalone components / component behaviors with their own separate API. - - -### Component composition > component inheritance. - -A component’s API needs to *primarily* focus on passing along data to the component itself (which can include how nested components are positioned / behave) + whatever nested children should get passed along. - -Shorthand API config options to nested components are ok for frequently nested subcomponents *however* aren’t a replacement for the full “longhand” version of nesting something. - - -- In components that include a shorthand way to pre-configure nested subcomponents and behavior (ex. nested icons or linkable behavior), how are we handling additional subcomponent options that are out of scope for what a ‘shorthand” API should reasonably handle? - - -*Probably* Reasonable: -``` - - - - - Hello world - - - - - - Hello world - -``` - -*Probably* **Not** Reasonable: -``` - - - Hello world - - - - - - Hello world - - - -``` - - -> When in doubt, it’s better to avoid including a shorthand API for a nested sub-component entirely if it’ll mean having a component with a smaller, more consistent, easier to maintainable API. - - -### Don’t repeat yourself. -Look at the component’s Twig, Sass and JavaScript files independently. - -- Are there any patterns or logic that stick out as occurring multiple times? -- Could a loop or helper function *significantly* cut back on the amount of code getting written? -- Does adding a new value to a list of already available options involve more than updating an array? -- Does adding a new prop type require copying and pasting the same couple lines of code over and over again? - - - -### Use the web component rendering engine best suited for a component’s needs (Preact vs Lit-HTML) -Currently there are two different component rendering engines available in Bolt to handle different use cases (each with their pros and cons — see below), Preact (JSX) and Lit-HTML (Template Literals). - -While both are great choices and would both work great in many situations (and in those cases, which engine to use is really up to the author’s personal preference), there are 2 important use cases that must get considered when settling on one renderer over the other. - - -**1. Dynamic Template Tags** -Do you need dynamic template tags in your HTML (ex. dynamically switch between an `

` or a `

` depending on a prop passed along)? - -If so, currently **only** Preact has this use case figured out (but this could change down the road). Currently, the only known way to have dynamic tags in Lit-HTML involves lots of “if / else” statements and manually doing the work yourself. - -**Dynamic Support** -On the flip side, does the component need to support conditionally rendered `` tags in the template based on native Shadow DOM support? If not, would a heavy handed `this.innerHTML` JavaScript call potentially break any event bindings? - -If so, currently **only** Lit-HTML has this use case figured out (however as with Dynamic Tags, this could ultimately change down the road). - - -### Preact vs Lit-HTML Renderers - -**Option A. [Preact](https://github.com/bolt-design-system/bolt/blob/master/packages/core/renderers/renderer-preact.js)** -- **Pros** - - JSX templates = POWERFUL - - **Tons** of examples out there for Preact / React - - Relatively straightforward to port React components over from NPM - - Ability to import and nest JSX components in other components (ex. `