Asides like Tip don't have coloring but should

ktoso commented 2 years ago

Description

Asides like "Tip" and "Experiment" don't have colors in the default theme but should.

Apple's own docs have coloring, so while developing my own docs it looks as if docc was broken since it did not color my Tip boxes -- but it just was missing styling.

See:

Apple theme: Screenshot 2022-07-22 at 7 44 06

vs OSS theme: Screenshot 2022-07-22 at 7 44 16

These should be colored by default so the package ecosystem has a consistent good looking aside style.

We can just use the same colors as the apple theme:

    --color-aside-deprecated: var(--color-figure-gray);
    --color-aside-experiment: var(--color-figure-gray);
    --color-aside-experiment-background: var(--color-fill-gray-secondary);
    --color-aside-experiment-border: var(--color-figure-light-gray);
    --color-aside-important: var(--color-figure-gray);
    --color-aside-important-background: var(--color-fill-gray-secondary);
    --color-aside-important-border: var(--color-figure-light-gray);
    --color-aside-note: var(--color-figure-gray);
    --color-aside-note-background: var(--color-fill-gray-secondary);
    --color-aside-tip: var(--color-figure-gray);
    --color-aside-tip-background: var(--color-fill-gray-secondary);
    --color-aside-tip-border: var(--color-figure-light-gray);
    --color-aside-warning: var(--color-figure-gray);

        --color-fill: #000;
        --color-fill-secondary: #161617;
        --color-fill-tertiary: #1d1d1f;
        --color-fill-blue: #0071e3;
        --color-fill-light-blue-secondary: #002a51;
        --color-fill-gray: #f5f5f7;
        --color-fill-gray-secondary: #6e6e73;
        --color-fill-gray-tertiary: #424245;
        --color-fill-gray-quaternary: #333336;
        --color-fill-green-secondary: #002b03;
        --color-fill-orange-secondary: #290d00;
        --color-fill-red-secondary: #300;
        --color-figure-blue: #2997ff;
        --color-figure-gray: #f5f5f7;
        --color-figure-gray-secondary: #86868b;
        --color-figure-gray-secondary-alt: #a1a1a6;
        --color-figure-gray-tertiary: #6e6e73;
        --color-figure-green: #03a10e;
        --color-figure-light-gray: #9a9a9e;
        --color-figure-orange: #f56300;
        --color-figure-red: #ff3037;

https://developer.apple.com/tutorials/css/chunk-vendors.75afc065.css

Checklist

[X] If possible, I've reproduced the issue using the main branch of this package.
[X] This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Aside boxes should have good coloring by default

Actual behavior

All aside boxes are gray.

Steps To Reproduce

No response

Swift-DocC-Render Version Information

Swift 5.7

SamLanier commented 2 years ago

The default styling for DocC Render specifically uses a separate color palette than what is used for Apple Documentation. We currently try to use basic hex colors in DocC Render, which are more common and brand-agnostic, in order to appeal to a wide variety of users.

Can you propose some other color values that fit these parameters?

ktoso commented 2 years ago

Sure, let's see -- how about something like these? Color getting "hotter" the more important/urgent the aside is:

So like these below; Though I'm not accessibility expert and not sure if those need to be more intense or not... but they're around the same color tone as we've used in other places so maybe okey?

#F2FCFF - Note
#F2FFF6 - Tip
#FFFEF2 - Important
#FFF2F2 - Warning
#FFF8F2 - Experiment

<html>
<head>
  <style>
  td {
    padding: 15px;
  }
  </style>
</head>
<body>
<table style="padding:10px;">
<tr style="background-color:#F2FCFF;">
  <td><b>Note</b></td>
  <td>
    General information that applies to some users.
  </td>
</tr>
<tr style="background-color:#F2FFF6">
  <td><b>Tip</b></td>
  <td>Helpful information, such as shortcuts, suggestions, or hints.</td>
</tr>
<tr style="background-color:#FFFEF2;padding:10px;">
  <td><b>Important</b></td>
  <td>
    Important information, such as a requirement.
  </td>
</tr>
<tr style="background-color:#FFF8F2">
  <td><b>Experiment</b></td>
  <td>Instructional information to reinforce a learning objective, or to encourage developers to try out different parts of your framework.</td>
</tr>
<tr style="background-color:#FFF2F2">
  <td><b>Warning</b></td>
  <td>
    Critical information, like potential data loss or an irrecoverable state.
  </td>
</tr>
</table>
</body>
</html></html>

https://jsfiddle.net/0st53kxz/35/

ktoso commented 2 years ago

(note: it seems warning DOES have color, just tips don't) Screenshot 2022-07-25 at 18 36 04

mportiz08 commented 2 years ago

(note: it seems warning DOES have color, just tips don't)

Correct. The deprecated and warning asides are the only ones with a distinct non-gray color in swift-docc-render at the moment.

mportiz08 commented 2 years ago

\cc @willimholte

natikgadzhi commented 11 months ago

@mportiz08, @SamLanier, cool if I grab and work on this one?

SamLanier commented 11 months ago

Note that these will need a background color, border color, and a label color (if you want the aside heading to be colored). The border color and label color are the same in the example of an aside in our Apple Developer Documentation, and the background color is a -light variant of those colors. The background color must also meet contrast ratio requirements for text, which can be easily calculated with a tool like this.

mportiz08 commented 11 months ago

@natikgadzhi sure thing. I would suggest running the colors by @SamLanier and adding her as a reviewer to the PR. Also, I should call out that we will want to have light/dark variants for the colors that she described. Feel free to reach out if you have any questions about the code related to the colors and someone on the DocC-Render team can help you out.

\cc @marinaaisa @hqhhuang @dobromir-hristov

swiftlang / swift-docc-render