Rework API reference pages

chrome/common/extensions/docs/static/sass/_api.scss

Index: chrome/common/extensions/docs/static/sass/_api.scss
diff --git a/chrome/common/extensions/docs/static/sass/_api.scss b/chrome/common/extensions/docs/static/sass/_api.scss
new file mode 100644
index 0000000000000000000000000000000000000000..93cb9764613965783d8d2b382ff5607d97812c1e
--- /dev/null
+++ b/chrome/common/extensions/docs/static/sass/_api.scss
@@ -0,0 +1,53 @@
+.api {
+  color: #333;

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Contrast ratio 12.6:1.

I wonder if we should comment these in the CSS so that we remember to strictly
avoid falling below the WCAG rules, and to try to avoid low-contrast text in
places we want people to read. I'm computing contrasts with
http://webaim.org/resources/contrastchecker/.

[Renato Mangini (chromium), 2014/02/14 00:50:50]

Good point. As you noticed, at least for API pages I've made text darker while
we wait designers clearance to also apply it to the rest.

Checking contrast ratio and WCAG rules is a good tip, but I think it should be
done by designers, not in CSS. The additional comments would make the CSS harder
to maintain, since it would need to be changed whenever the background color
changes - and would only make sense if the text is used in a single background.

On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:

+  font-size: 14px;
+
+  .api-summary {

[Jeffrey Yasskin, 2014/02/07 02:40:03]

This hasn't been propagated to the compiled css, which means my attempt to look
at the UI didn't give me the expected results.

I understand this is going to be more automatic in the future.

[Renato Mangini (chromium), 2014/02/14 00:50:50]

You need to compile SASS files. And yes, it will be more automatic when SASS
native support is added (AFAIK CL in progress by hukun)

On 2014/02/07 02:40:03, Jeffrey Yasskin wrote:

+    td, th {
+      padding: 5px 10px;
+    }
+    a {
+      color: inherit;
+      font-weight: normal;
+    }
+    td:hover a, td:hover a * {

[Jeffrey Yasskin, 2014/02/07 02:40:03]

We shouldn't have a UI that requires you to scan your mouse over the page in
order to find what's interactive. Besides being annoying, it doesn't work at all
on mobile.

[Renato Mangini (chromium), 2014/02/14 00:50:50]

Done. Added a link with the function name and the syntax highlighted signature
with no link.

+      cursor: pointer;
+      color: $link-color;
+      font-weight: bold;

[Jeffrey Yasskin, 2014/02/07 02:40:03]

We shouldn't change the size of text on hover. It causes unpleasant jumping
effects.

[Renato Mangini (chromium), 2014/02/14 00:50:50]

Done.

+    }
+  }
+
+  .api-reference {
+    .description {
+      margin-left: 20px;
+    }
+    table.innerTable {
+      margin: 10px 0;
+      td, th {
+        padding: 5px 10px;
+        border: 1px solid #eee;
+      }
+      th {
+        background: none;

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Please comment which background this cancels.

+      }
+      p {
+        margin: 0;

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Do we have any places where we have 2 paragraphs in an innerTable? If so, this
is going to remove all the space between them, which seems less than ideal. You
could get it back with "p+p{margin-top:whatever}".

+      }
+    }
+    td, th {
+      border: 1px solid #eee;
+    }
+    th {
+      background: #fafafa;

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Contrast ratio 12.1:1

+    }
+    h2 {
+      background-color: darken($gray-light, 5%);

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Contrast ratio 17.1:1

+      padding: $default-padding;
+      margin-left: $default-padding * -1;
+      margin-right: $default-padding * -1;
+    }
+    h3 {
+      margin-top: rhythm(2);

[Jeffrey Yasskin, 2014/02/07 02:40:03]

Is there a good way to search for the definitions of functions like this? I had
to click through most of the compass site before I found
http://compass-style.org/reference/compass/typography/vertical_rhythm/#functi...,
and even that doesn't explain what a "rhythm" or rhythm unit is. If I'm not just
missing an obvious reference, please comment this.

[Renato Mangini (chromium), 2014/02/14 00:50:50]

Done.

+    }
+  }
+}